91
92
Webhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.
93
94
-1. Set your webhook URL in [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events)
94
+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)
95
2. Build an endpoint that accepts POST requests with JSON payloads
96
97
<Callout type="info">
98
**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server for testing.
99
</Callout>
100
101
+Composio delivers two event types via webhooks:
102
+
103
+| Event type | Description |
104
+|------------|-------------|
105
+| `composio.trigger.message` | Trigger events from connected apps (all versions) |
106
+| `composio.connected_account.expired` | OAuth2 connection expired and needs re-authentication (V3 only) |
107
+
108
### Webhook payload (V3)
109
103
-New organizations receive V3 payloads by default. The payload separates event metadata from the actual event data:
110
+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:
111
112
```json
113
{
107
- "id": "wh_abc123",
108
- "type": "github_commit_event",
114
+ "id": "msg_abc123",
115
+ "type": "composio.trigger.message",
116
"metadata": {
110
- "triggerId": "ti_xyz789",
111
- "connectedAccountId": "ca_def456",
112
- "userId": "user-id-123435",
113
- "toolkitSlug": "github"
117
+ "trigger_slug": "GITHUB_COMMIT_EVENT",
118
+ "trigger_id": "ti_xyz789",
119
+ "connected_account_id": "ca_def456",
120
+ "auth_config_id": "ac_xyz789",
121
+ "user_id": "user-id-123435"
122
},
123
"data": {
124
"commit_sha": "a1b2c3d",
142
async def webhook_handler(request: Request):
143
payload = await request.json()
144
137
- trigger_type = payload.get("type")
145
+ metadata = payload.get("metadata", {})
146
+ trigger_slug = metadata.get("trigger_slug")
147
event_data = payload.get("data", {})
148
140
- if trigger_type == "github_commit_event":
149
+ if trigger_slug == "GITHUB_COMMIT_EVENT":
150
commit = event_data.get("message")
151
author = event_data.get("author")
152
print(f"New commit by {author}: {commit}")
163
// ---cut---
164
export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
165
const payload = req.body;
166
+ const triggerSlug = payload.metadata?.trigger_slug;
167
158
- if (payload.type === 'github_commit_event') {
168
+ if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
169
const event: TriggerEvent<GitHubCommitEventData> = {
170
type: payload.type,
171
timestamp: payload.timestamp,