Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: fix V3 payload format and add webhook subscriptions API references

Sushmithamalleshc722b2947a54
diff --git a/docs/content/docs/setting-up-triggers/index.mdx b/docs/content/docs/setting-up-triggers/index.mdx
index 72c91fab9..b342efb56 100644
--- a/docs/content/docs/setting-up-triggers/index.mdx
+++ b/docs/content/docs/setting-up-triggers/index.mdx
@@ -91,26 +91,34 @@ The trigger instance uses the toolkit version configured during Composio initial
Webhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.
-1. Set your webhook URL in [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events)
+1. Set your webhook URL in the [dashboard settings](https://platform.composio.dev?next_page=/settings/events) or via the [Webhook Subscriptions API](/reference/api-reference/webhooks)
2. Build an endpoint that accepts POST requests with JSON payloads
<Callout type="info">
**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server for testing.
</Callout>
+Composio delivers two event types via webhooks:
+
+| Event type | Description |
+|------------|-------------|
+| `composio.trigger.message` | Trigger events from connected apps (all versions) |
+| `composio.connected_account.expired` | OAuth2 connection expired and needs re-authentication (V3 only) |
+
### Webhook payload (V3)
-New organizations receive V3 payloads by default. The payload separates event metadata from the actual event data:
+New organizations receive V3 payloads by default. V3 uses a standardized `type` field (`composio.trigger.message`) and separates event metadata from the actual event data:
```json
{
- "id": "wh_abc123",
- "type": "github_commit_event",
+ "id": "msg_abc123",
+ "type": "composio.trigger.message",
"metadata": {
- "triggerId": "ti_xyz789",
- "connectedAccountId": "ca_def456",
- "userId": "user-id-123435",
- "toolkitSlug": "github"
+ "trigger_slug": "GITHUB_COMMIT_EVENT",
+ "trigger_id": "ti_xyz789",
+ "connected_account_id": "ca_def456",
+ "auth_config_id": "ac_xyz789",
+ "user_id": "user-id-123435"
},
"data": {
"commit_sha": "a1b2c3d",
@@ -134,10 +142,11 @@ See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#we
async def webhook_handler(request: Request):
payload = await request.json()
- trigger_type = payload.get("type")
+ metadata = payload.get("metadata", {})
+ trigger_slug = metadata.get("trigger_slug")
event_data = payload.get("data", {})
- if trigger_type == "github_commit_event":
+ if trigger_slug == "GITHUB_COMMIT_EVENT":
commit = event_data.get("message")
author = event_data.get("author")
print(f"New commit by {author}: {commit}")
@@ -154,8 +163,9 @@ type GitHubCommitEventData = { commit_sha: string; message: string; author: stri
// ---cut---
export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
const payload = req.body;
+ const triggerSlug = payload.metadata?.trigger_slug;
- if (payload.type === 'github_commit_event') {
+ if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
const event: TriggerEvent<GitHubCommitEventData> = {
type: payload.type,
timestamp: payload.timestamp,
diff --git a/docs/content/docs/setting-up-triggers/webhook-verification.mdx b/docs/content/docs/setting-up-triggers/webhook-verification.mdx
index 456e89bc8..c534516a3 100644
--- a/docs/content/docs/setting-up-triggers/webhook-verification.mdx
+++ b/docs/content/docs/setting-up-triggers/webhook-verification.mdx
@@ -46,9 +46,9 @@ type Response = { status: (code: number) => { json: (data: any) => void; send: (
// ---cut---
const composio = new Composio({ apiKey: 'your-api-key' });
-function handleWebhook(req: Request, res: Response) {
+async function handleWebhook(req: Request, res: Response) {
try {
- const result = composio.triggers.verifyWebhook({
+ const result = await composio.triggers.verifyWebhook({
payload: req.body,
signature: req.headers['webhook-signature'],
id: req.headers['webhook-id'],
@@ -158,13 +158,14 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep
```json
{
- "id": "wh_abc123",
- "type": "github_commit_event",
+ "id": "msg_abc123",
+ "type": "composio.trigger.message",
"metadata": {
- "triggerId": "ti_xyz789",
- "connectedAccountId": "ca_def456",
- "userId": "user-id-123435",
- "toolkitSlug": "github"
+ "trigger_slug": "GITHUB_COMMIT_EVENT",
+ "trigger_id": "ti_xyz789",
+ "connected_account_id": "ca_def456",
+ "auth_config_id": "ac_xyz789",
+ "user_id": "user-id-123435"
},
"data": {
"commit_sha": "a1b2c3d",
@@ -211,8 +212,14 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep
## Configuring your webhook URL and secret
+You can configure webhooks via the dashboard or the [Webhook Subscriptions API](/reference/api-reference/webhooks):
+
1. Go to [Project Settings > Webhook](https://platform.composio.dev?next_page=/settings/webhook)
2. Enter your publicly accessible webhook URL
3. Copy the webhook secret and store it as the `COMPOSIO_WEBHOOK_SECRET` environment variable
The SDK reads `COMPOSIO_WEBHOOK_SECRET` automatically when using `verifyWebhook()`.
+
+<Callout>
+The Webhook Subscriptions API also supports event filtering — subscribe only to `composio.trigger.message`, `composio.connected_account.expired`, or both. See the [API reference](/reference/api-reference/webhooks) for details.
+</Callout>
diff --git a/docs/content/docs/triggers.mdx b/docs/content/docs/triggers.mdx
index 16c3f5703..acb15cb05 100644
--- a/docs/content/docs/triggers.mdx
+++ b/docs/content/docs/triggers.mdx
@@ -17,8 +17,9 @@ There are two delivery types:
1. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)
2. **Create** an active trigger scoped to a user's connected account
-3. **Receive events**: Composio delivers payloads to your webhook endpoint
-4. **Manage**: enable, disable, or delete triggers as needed
+3. **Configure** your webhook endpoint so Composio knows where to deliver events
+4. **Receive events**: Composio sends payloads to your endpoint
+5. **Manage**: enable, disable, or delete triggers as needed
<Accordions>
<Accordion title="What is a trigger type?">