Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 23:30 UTC
docs(changelog): add composio.trigger.disabled webhook event
New V3 webhook event that fires when Composio automatically disables a trigger (connection expired, webhook refresh failure, polling unhealthy). Opt-in. Documents the four platform disable reasons, when it does and does not fire, the payload shape, and handler wiring. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Anshu Garg committed
Apr 22, 2026 at 22:29 UTC
3dabab76ddffe47fd9a01270fa5d8f21e99bb2a2
1 file changed
+94
docs/content/changelog/04-22-26-trigger-disabled-event.mdx
new
+94
@@ -0,0 +1,94 @@
1
+---
2
+title: "Webhook Event for Auto-Disabled Triggers"
3
+description: "New composio.trigger.disabled event fires when Composio disables a trigger on your behalf — expired connection, webhook refresh failure, or unhealthy polling. Opt-in, V3-only."
4
+date: "2026-04-22"
5
+---
6
+
7
+`composio.trigger.disabled` is a new V3 webhook event that fires when Composio disables one of your triggers without a request from you — expired credentials, a failed webhook-subscription refresh, or unhealthy polling. It's opt-in: add it to a webhook subscription's `enabled_events` to receive it. Existing subscriptions for `composio.trigger.message` and `composio.connected_account.expired` are unaffected.
8
+
9
+## When it fires
10
+
11
+The event is emitted only for platform-initiated disables. `data.disabled_reason` names the cause:
12
+
13
+| `disabled_reason` | What it means |
14
+|---|---|
15
+| `connection_expired` | The connected account entered `EXPIRED` and the trigger was paused. Auto-re-enabled when the account returns to `ACTIVE`. |
16
+| `subscription_auth_failure` | Composio tried to refresh the provider-side webhook subscription and the provider rejected the credential. |
17
+| `subscription_refresh_failure` | Composio tried to refresh the provider-side webhook subscription and retries ran out. |
18
+| `polling_failure_in_composio_infra` | A polling trigger was reported unhealthy by Composio's polling infrastructure. |
19
+
20
+The event does not fire when you disable a trigger yourself — neither through the trigger instance manage endpoint nor by deactivating the connected account with `PATCH /api/v3/connected_accounts/{nanoid}/status`.
21
+
22
+## Subscribe
23
+
24
+Add `composio.trigger.disabled` to your subscription's `enabled_events`:
25
+
26
+```bash
27
+curl -X POST https://backend.composio.dev/api/v3.1/webhook_subscriptions \
28
+ -H "X-API-KEY: <your-composio-api-key>" \
29
+ -H "Content-Type: application/json" \
30
+ -d '{
31
+ "webhook_url": "https://example.com/webhook",
32
+ "enabled_events": [
33
+ "composio.trigger.message",
34
+ "composio.trigger.disabled"
35
+ ]
36
+ }'
37
+```
38
+
39
+The event is V3-only. Subscriptions on V1 or V2 payloads cannot enable it.
40
+
41
+## Payload
42
+
43
+```json
44
+{
45
+ "id": "msg_abc123",
46
+ "type": "composio.trigger.disabled",
47
+ "metadata": {
48
+ "project_id": "pr_your-project-id",
49
+ "org_id": "your-org-id"
50
+ },
51
+ "data": {
52
+ "id": "ti_xyz789",
53
+ "connected_account_id": "ca_def456",
54
+ "trigger_name": "GITHUB_COMMIT_EVENT",
55
+ "user_id": "user-id-12345",
56
+ "version": "20260315_00",
57
+ "trigger_config": { "owner": "composio", "repo": "hermes" },
58
+ "updated_at": "2026-04-22T11:59:59.000Z",
59
+ "disabled_at": "2026-04-22T11:59:59.000Z",
60
+ "disabled_reason": "connection_expired"
61
+ },
62
+ "timestamp": "2026-04-22T12:00:00.000Z"
63
+}
64
+```
65
+
66
+`user_id` is `null` on triggers from toolkits that do not require authentication. The `data` object mirrors the non-deprecated fields returned per item by `GET /api/v3/trigger_instances/active`, plus `disabled_reason`.
67
+
68
+## Handling
69
+
70
+Route on `type` alongside your existing handlers:
71
+
72
+```typescript
73
+type NextApiRequest = { body: any };
74
+type NextApiResponse = { status: (code: number) => { json: (data: any) => void } };
75
+// ---cut---
76
+export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
77
+ const payload = req.body;
78
+
79
+ if (payload.type === 'composio.trigger.disabled') {
80
+ const { id, connected_account_id, trigger_name, disabled_reason } = payload.data;
81
+
82
+ if (disabled_reason === 'connection_expired') {
83
+ // Prompt the user to re-authenticate; the trigger re-enables on its own.
84
+ } else {
85
+ // subscription_auth_failure, subscription_refresh_failure, polling_failure_in_composio_infra
86
+ // These do not auto-re-enable — inspect the trigger and re-enable once resolved.
87
+ }
88
+ }
89
+
90
+ res.status(200).json({ status: 'ok' });
91
+}
92
+```
93
+
94
+For general webhook setup, see [subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events); for re-auth flows on connection expiry, see [subscribing to connection expiry events](/docs/subscribing-to-connection-expiry-events).