Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs(changelog): add composio.trigger.disabled webhook event
Anshu Garg3dabab76ddff
diff --git a/docs/content/changelog/04-22-26-trigger-disabled-event.mdx b/docs/content/changelog/04-22-26-trigger-disabled-event.mdxnew file mode 100644index 000000000..94692b0a1--- /dev/null+++ b/docs/content/changelog/04-22-26-trigger-disabled-event.mdx@@ -0,0 +1,94 @@+---+title: "Webhook Event for Auto-Disabled Triggers"+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."+date: "2026-04-22"+---++`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.++## When it fires++The event is emitted only for platform-initiated disables. `data.disabled_reason` names the cause:++| `disabled_reason` | What it means |+|---|---|+| `connection_expired` | The connected account entered `EXPIRED` and the trigger was paused. Auto-re-enabled when the account returns to `ACTIVE`. |+| `subscription_auth_failure` | Composio tried to refresh the provider-side webhook subscription and the provider rejected the credential. |+| `subscription_refresh_failure` | Composio tried to refresh the provider-side webhook subscription and retries ran out. |+| `polling_failure_in_composio_infra` | A polling trigger was reported unhealthy by Composio's polling infrastructure. |++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`.++## Subscribe++Add `composio.trigger.disabled` to your subscription's `enabled_events`:++```bash+curl -X POST https://backend.composio.dev/api/v3.1/webhook_subscriptions \+ -H "X-API-KEY: <your-composio-api-key>" \+ -H "Content-Type: application/json" \+ -d '{+ "webhook_url": "https://example.com/webhook",+ "enabled_events": [+ "composio.trigger.message",+ "composio.trigger.disabled"+ ]+ }'+```++The event is V3-only. Subscriptions on V1 or V2 payloads cannot enable it.++## Payload++```json+{+ "id": "msg_abc123",+ "type": "composio.trigger.disabled",+ "metadata": {+ "project_id": "pr_your-project-id",+ "org_id": "your-org-id"+ },+ "data": {+ "id": "ti_xyz789",+ "connected_account_id": "ca_def456",+ "trigger_name": "GITHUB_COMMIT_EVENT",+ "user_id": "user-id-12345",+ "version": "20260315_00",+ "trigger_config": { "owner": "composio", "repo": "hermes" },+ "updated_at": "2026-04-22T11:59:59.000Z",+ "disabled_at": "2026-04-22T11:59:59.000Z",+ "disabled_reason": "connection_expired"+ },+ "timestamp": "2026-04-22T12:00:00.000Z"+}+```++`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`.++## Handling++Route on `type` alongside your existing handlers:++```typescript+type NextApiRequest = { body: any };+type NextApiResponse = { status: (code: number) => { json: (data: any) => void } };+// ---cut---+export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {+ const payload = req.body;++ if (payload.type === 'composio.trigger.disabled') {+ const { id, connected_account_id, trigger_name, disabled_reason } = payload.data;++ if (disabled_reason === 'connection_expired') {+ // Prompt the user to re-authenticate; the trigger re-enables on its own.+ } else {+ // subscription_auth_failure, subscription_refresh_failure, polling_failure_in_composio_infra+ // These do not auto-re-enable — inspect the trigger and re-enable once resolved.+ }+ }++ res.status(200).json({ status: 'ok' });+}+```++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).