Skip to main content
Use this page when MeshAgent needs to call your service or toolkit over the webhook transport. This is different from standard project webhooks. For project event delivery such as room.started or storage.file.updated, see Projects > Webhooks.

​
When to use WebhookServer

Use WebhookServer when your endpoint needs:
  • built-in signature verification
  • a default GET / health check
  • a default POST /webhook handler
  • support for room.call handoffs, including websocket upgrades

​
What room.call sends

For room.call, MeshAgent sends:
  • room_name
  • room_url
  • token
  • optional arguments
That is the handoff MeshAgent uses when it calls your own service endpoint.

​
Configure webhook verification

Set the webhook secret if you want the server to verify signed requests: 
export MESHAGENT_WEBHOOK_SECRET=your-secret
For local development, you can disable verification with validate_webhook_secret=False.

​
Run WebhookServer

The built-in server listens on port 8080 by default and exposes:
  • GET / for health checks
  • POST /webhook for webhook delivery
  • GET /webhook for websocket upgrades used by room.call
Use the SDK to create the server and handle room.call: 
from meshagent.api.webhooks import (
    WebhookServer,
    CallEvent,
)
import asyncio


class CustomWebhookServer(WebhookServer):
    async def on_call(self, event: CallEvent):
        print(f"room call for {event.room_name}")
        print(f"arguments: {event.arguments}")


async def main():
    server = CustomWebhookServer()
    await server.run()


asyncio.run(main())

​
Standard project webhooks

If you just want MeshAgent to notify an external system about project events, you do not need WebhookServer. Create a standard project webhook instead: 
meshagent webhook create \
  --name room-events \
  --url https://example.com/webhook \
  --event room.started \
  --event room.ended
That setup is covered in Projects > Webhooks.