Receive events locally
While developing, you want trigger events on your machine. The best option forwards them to the real webhook handler you’ll run in production, so you test the exact path (includingparse() and signature verification) before you ship.
Quick look with subscribe()
subscribe() streams events straight to your process over a WebSocket, with no webhook URL, no tunnel, and no signing. It’s the fastest way to eyeball what a trigger sends, but it bypasses your real webhook handler. Use it only for basic prototyping; for anything you intend to ship, forward events to your handler with one of the options below.
Under the hood
subscribe() opens the WebSocket via Pusher. This is an implementation detail, but worth knowing if your runtime restricts WebSocket clients — prefer the webhook/forwarding options below for anything you ship.- Python
- TypeScript
triggerId, triggerSlug, connectedAccountId, toolkits, or userId, or pass no filters to receive every trigger event in the project.
Subscription failures (for example a rejected auth request) do not reject the subscribe() promise in TypeScript — Pusher reports them asynchronously after it resolves. Pass an error callback to react to them programmatically: the on_subscription_error keyword in Python, or an optional third argument in TypeScript. In Python, failures raised while establishing the subscription (such as an auth rejection) invoke the callback and then re-raise from subscribe() instead of timing out.
- Python
- TypeScript
Forward to your local handler with the CLI (recommended)
The Composio CLI streams realtime events and forwards each one to your local URL, signed exactly like production. No public URL, no tunnel, and it runs your real handler (andparse()) end to end.
COMPOSIO_WEBHOOK_SECRET if it’s set, otherwise the CLI prints a generated secret to verify against. Filter the stream with --toolkits, --trigger-slug, or --trigger-id, and tee events to a file with --out events.jsonl.
Cloudflare Tunnel
Expose your local server with Cloudflare Tunnel, no account needed for quick runs:trycloudflare.com URL as your webhook URL, then events reach your handler at http://localhost:8000/webhooks/composio.
ngrok
Expose your local server with ngrok:ngrok-free.app URL as your webhook URL the same way.
Receive events in production
Register your webhook URL once per project. Composio thenPOSTs every trigger event to it. Set it from the SDK:
- Python
- TypeScript
- API
Manage project subscriptions
Usecomposio.webhooks.subscriptions to manage outbound delivery from your project. Both SDKs provide list(), get(), set(), update(), and delete(). Rotate signing secrets with rotate_secret() in Python or rotateSecret() in TypeScript, and discover supported events with list_event_types() or listEventTypes().
For inbound events from a provider’s OAuth app, use webhook endpoints.
Handling events
In your handler, pass the incoming request toparse(). It returns the typed, normalized payload. Pass verifySecret and it verifies the signature first, so one call both authenticates and parses.
- Python
- TypeScript
Composio delivers other project events (like connection expiry) to this same URL.
parse() returns those too. Route on result.payload.triggerSlug and ignore what you don’t handle.Inspecting trigger payload schemas
Each trigger type declares the shape of thedata it sends. Inspect it before you write your handler:
- Python
- TypeScript
- API
--toolkits), so your handler is type-checked against the trigger’s payload:
Webhook payload shape
Every trigger event arrives in the same envelope.metadata tells you where the event came from; data holds the event itself, in the shape the trigger type declares.
This is the V3 payload, the default for new organizations. See webhook payload versions for V2 and V1.
Verifying signatures
Composio signs every webhook request.parse({ verifySecret }) verifies the signature for you (and verifyWebhook() does the same at a lower level), so most handlers need nothing more. You only need this section if you’re not using the Composio SDK.
Store the webhook secret securely as
COMPOSIO_WEBHOOK_SECRET. Fetch it from the webhook subscription any time, or rotate it if it leaks.webhook-signature, webhook-id, and webhook-timestamp headers. Compute HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{rawBody} with your secret and compare it against the signature:
- Python
- TypeScript
Reject requests whose
webhook-timestamp is too old to block replays. The SDK’s parse() and verifyWebhook() enforce a 300-second tolerance by default; pass tolerance to change it, or 0 to disable the check.Webhook payload versions
parse() and verifyWebhook() auto-detect the version. If you process payloads manually, here are the formats:
- V3 (default)
- V2 (legacy)
- V1 (legacy)
Metadata is separated from event data. New organizations receive V3 payloads by default.