Skip to main content

​
Overview

Webhooks let MeshAgent notify your systems when events occur. Instead of polling, you register a webhook URL (from MeshAgent Studio) and MeshAgent delivers event payloads in real time. Common uses:
  • Trigger a workflow when a room starts or ends.
  • Sync files to an external system.
  • Kick off automation when specific events happen in a room.

​
Event types

MeshAgent emits a small set of core webhook events. You can subscribe to specific events or use * to receive all.
  • room.started - Room session started. Payload includes room_name.
  • room.ended - Room session ended. Payload includes room_name.
  • storage.file.updated - File written or updated. Payload includes path and participant_id.
  • storage.file.deleted - File deleted. Payload includes path and participant_id.
  • * - Receive all events.

​
Payload format

Webhook requests are sent as JSON: 
{
  "event": "room.started",
  "data": {
    "room_name": "my-room"
  }
}

​
Delivery and verification

If you set a webhook secret, MeshAgent signs each request and sends a Meshagent-Signature header.
  • The header value is Bearer <jwt>.
  • The JWT contains a SHA-256 hash of the payload.
  • The SDK WebhookServer verifies the signature automatically when a secret is set.
Set the secret in your environment: 
export MESHAGENT_WEBHOOK_SECRET=your-secret

​
Built-in WebhookServer

MeshAgent provides a helper server so you can focus on handling events. It listens on port 8080 by default and exposes:
  • GET / for health checks.
  • POST /webhook for webhook delivery.
Use the SDK to create a server and handle events: 
from meshagent.api.webhooks import WebhookServer, RoomStartedEvent, RoomEndedEvent
import asyncio


class CustomWebhookServer(WebhookServer):
    async def on_room_started(self, event: RoomStartedEvent):
        print(f"room started {event.room_name}")
        pass

    async def on_room_ended(self, event: RoomEndedEvent):
        print(f"room ended {event.room_name}")
        pass


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


asyncio.run(main())

​
Next steps