Skip to main content
Once a trigger is active, its events come to you as the same payload, whether you’re testing locally or running in production. Develop against your local handler first, then point Composio at your production URL when you ship.

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 (including parse() 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.
Filter the stream by 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.
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 (and parse()) end to end.
Events are signed with 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:
Register the printed 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:
Register the printed ngrok-free.app URL as your webhook URL the same way.

Receive events in production

Register your webhook URL once per project. Composio then POSTs every trigger event to it. Set it from the SDK:
Your webhook endpoint must be publicly reachable. Composio’s outbound IPs are dynamic, so IP allowlists and VPN-only endpoints won’t work. Authenticate payloads with signature verification instead.

Manage project subscriptions

Use composio.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 to parse(). It returns the typed, normalized payload. Pass verifySecret and it verifies the signature first, so one call both authenticates and parses.
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 the data it sends. Inspect it before you write your handler:
From the CLI, inspect a single trigger type’s config and payload schema:
Or generate typed stubs for your project (scope to the toolkits you use with --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.
Every request includes 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:
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:
Metadata is separated from event data. New organizations receive V3 payloads by default.

Next

Managing triggers