@devries-cameron20 / composio Mirror · read-only / commits / 3dabab76d
Fork 0

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).