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(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.mdx
new file mode 100644
index 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).