Webhook Subscriptions API & Connection Expiry Events

A new API for managing webhook configurations with event filtering, HMAC signature verification, and support for platform lifecycle events. This replaces the legacy project-level webhook settings with a more flexible, subscription-based model.

Summary

API Overview

See the API Reference for complete details.

Endpoints

Key Capabilities

• Event filtering: Subscribe only to events you need
• HMAC-SHA256 signatures: Every webhook includes a cryptographic signature for verification
• Secret rotation: Rotate signing secrets on demand

Creating a Subscription

curl -X POST "https://backend.composio.dev/api/v3/webhook_subscriptions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-server.com/webhooks/composio",
    "enabled_events": ["composio.trigger.message"],
    "version": "V3"
  }'

Response:

{
  "id": "ws_your-subscription-id",
  "webhook_url": "https://your-server.com/webhooks/composio",
  "version": "V3",
  "enabled_events": ["composio.trigger.message"],
  "secret": "<your-webhook-secret>",
  "created_at": "2026-02-06T12:00:00.000Z",
  "updated_at": "2026-02-06T12:00:00.000Z"
}

Notes

• 1 subscription per project: Currently limited to one webhook subscription per project. This will be expanded in future releases.
• HTTPS required: Webhook URLs must use HTTPS in production environments.

New Event: composio.connected_account.expired

A new platform event that notifies you when an OAuth2 connected account's authentication expires and cannot be automatically refreshed.

Use Cases

• Prompt users to re-authenticate before workflows fail
• Track connection health across your user base
• Automate re-connection flows
• Build proactive notification systems

Subscribing to Connection Expiry Events

curl -X POST "https://backend.composio.dev/api/v3/webhook_subscriptions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-server.com/webhooks/composio",
    "enabled_events": [
      "composio.trigger.message",
      "composio.connected_account.expired"
    ],
    "version": "V3"
  }'

Payload Structure

The composio.connected_account.expired event follows the V3 envelope format:

{
  "id": "evt_847cdfcd-d219-4f18-a6dd-91acd42ca94a",
  "timestamp": "2026-02-06T12:00:00.000Z",
  "type": "composio.connected_account.expired",
  "metadata": {
    "project_id": "pr_your-project-id",
    "org_id": "ok_your-org-id"
  },
  "data": {
    "toolkit": {
      "slug": "gmail"
    },
    "auth_config": {
      "id": "ac_your-auth-config-id",
      "auth_scheme": "OAUTH2",
      "is_composio_managed": true,
      "is_disabled": false
    },
    "id": "ca_your-connected-account-id",
    "status": "EXPIRED",
    "created_at": "2025-12-01T10:00:00.000Z",
    "updated_at": "2026-02-06T12:00:00.000Z",
    "status_reason": "OAuth refresh token expired",
    "is_disabled": false
  }
}

Verifying Webhook Signatures

All webhooks include an HMAC signature in the webhook-signature header. Use the SDK's built-in verification functions or see the Triggers documentation for implementation details.

Available Event Types

Query available events and their version compatibility:

curl "https://backend.composio.dev/api/v3/webhook_subscriptions/event_types" \
  -H "x-api-key: YOUR_API_KEY"

Deprecations

Deprecated Endpoints

The following legacy endpoints are deprecated and will be removed in a future release:

Deprecated Fields in Project Response

Backward Compatibility

What We've Done For You

• Automatic migration: We've created a webhook subscription for all existing projects that had webhook URLs configured, with composio.trigger.message enabled by default
• Same payload format: If you were using V1, V2, or V3 triggers, they continue with the same format

What Continues to Work

• Legacy webhook endpoints (deprecated but functional)
• Existing project webhook configurations
• All existing trigger payload formats (V1, V2, V3)
• Signature verification with your existing secret

Payload Version Comparison