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(triggers): list composio.trigger.disabled in supported events; tighten changelog reasons table

Anshu Garg409e7944afdd
diff --git a/docs/content/changelog/04-22-26-trigger-disabled-event.mdx b/docs/content/changelog/04-22-26-trigger-disabled-event.mdx
index 94692b0a1..5c01252b2 100644
--- a/docs/content/changelog/04-22-26-trigger-disabled-event.mdx
+++ b/docs/content/changelog/04-22-26-trigger-disabled-event.mdx
@@ -13,8 +13,8 @@ The event is emitted only for platform-initiated disables. `data.disabled_reason
| `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. |
+| `subscription_auth_failure` | The provider rejected the credentials when Composio tried to refresh the webhook subscription. Re-auth the connection to resolve. |
+| `subscription_refresh_failure` | Composio could not reach the provider to refresh the webhook subscription (provider error, timeout, or network issue). Re-enable the trigger once the provider is healthy. |
| `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`.
@@ -65,30 +65,4 @@ The event is V3-only. Subscriptions on V1 or V2 payloads cannot enable it.
`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).
+See [subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events) for handler setup and [subscribing to connection expiry events](/docs/subscribing-to-connection-expiry-events) for re-auth flows on `connection_expired`.
diff --git a/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
index 51b3ae824..d2f3c23df 100644
--- a/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+++ b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
@@ -6,12 +6,13 @@ keywords: [webhooks, subscribe, events, webhook payload, V3]
## Webhooks
-Webhooks are the recommended way to receive trigger events in production. To start receiving events, create a webhook subscription with your endpoint URL and select which event types you want to receive. You can subscribe to one or both:
+Webhooks are the recommended way to receive trigger events in production. To start receiving events, create a webhook subscription with your endpoint URL and select which event types you want to receive. You can subscribe to any combination:
| Event type | Description |
|------------|-------------|
-| `composio.trigger.message` | Fired when a trigger receives data from an external service |
+| `composio.trigger.message` | Fired when a trigger receives data from an external service. |
| `composio.connected_account.expired` | Fired when a connected account expires and needs re-authentication. See [Subscribing to connection expiry events](/docs/subscribing-to-connection-expiry-events). |
+| `composio.trigger.disabled` | Fired when Composio automatically disables a trigger (expired connection, webhook refresh failure, or unhealthy polling). Not fired when you disable a trigger or its connected account yourself. |
Set your webhook URL in the [dashboard settings](https://platform.composio.dev?next_page=/settings/webhook) or via the [Webhook Subscriptions API](/reference/api-reference/webhooks):