Triggers

Markdown

When events occur in apps, like a new Slack message, a GitHub commit, or an incoming email, triggers send event data to your application as structured payloads.

Triggers flow: Connected apps send events to Composio, which delivers them to your webhook endpoint via HTTP POST
How triggers deliver events from apps to your application

Two delivery types

TypeWhat happensExamples
WebhookThe provider posts events to a Composio-issued ingress URL in real time. Composio verifies the provider's signature, then fans the event out to matching trigger instances.Slack, GitHub, Asana, Notion, Outlook, ...
PollingComposio polls the provider on a schedule. Composio managed auth has a 15-minute minimum interval; expect that as the worst-case delay between source event and delivery.Gmail

The delivery type is a property of the trigger type, not something you choose.

Webhook endpoints

Every webhook trigger routes through a webhook endpoint — a project-scoped resource that owns the ingress URL the provider posts to and the signing secret used to verify each request. Endpoints are keyed by (toolkit_slug, project_id, client_id), so each OAuth app gets its own URL:

https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event

There are two ways an endpoint gets configured:

ConfigurationWhen it appliesWhat you do
Composio configures it for youComposio-managed OAuth apps (any toolkit) or your own OAuth app on a toolkit Composio can register webhooks for on your behalf using the connected user's credentials (e.g. Asana)Nothing — endpoint setup, signature verification, and provider-side registration happen automatically when you create the trigger
You configure itYour own OAuth app on a toolkit whose provider posts events at the OAuth-app level (today: Slack and Notion; more toolkits will follow on this same flow)Once per OAuth app, before creating triggers — see Configuring the webhook endpoint

If you use Composio-managed credentials, you don't need to configure anything — skip ahead to Creating triggers. Manual webhook-endpoint setup only applies when you bring your own OAuth app.

Checking which case applies to your toolkit

The single source of truth is the schema endpoint. Call it for the toolkit you're integrating; the response tells you exactly what to do.

curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug={toolkit_slug}" \
  -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
  • setup_fields is empty / not present → Composio configures the endpoint for you. Nothing to do.
  • setup_fields lists one or more fields → You configure the endpoint. The fields tell you what credentials to collect from the provider (signing secret, app-level token, etc.). Today this applies to Slack and Notion; the list will grow as more toolkits move onto this flow.

End-to-end flow

For every webhook trigger, an event takes the same path on the way to your application:

provider event ──▶ Composio ingress ──▶ trigger fan-out ──▶ webhook subscription ──▶ your endpoint

Two webhook URLs sit on opposite sides of Composio. Don't confuse them:

URLDirectionWho configures it
Ingress (/api/v3.1/webhook_ingress/...)Provider → ComposioComposio for most cases; you for your-own-OAuth on toolkits like Slack and Notion — see Webhook endpoints above
Webhook subscription (your URL)Composio → your applicationYou, once per project — see Subscribing to triggers

Composio verifies signatures on both hops:

  • At ingress, every inbound request is verified against the signing secret on the webhook endpoint. Unsigned or tampered requests are rejected before any trigger fires. For toolkits where Composio configures the endpoint, the signing secret is sourced from the connected account's credentials; for toolkits where you configure it, you store the secret on the endpoint yourself.
  • At delivery, every webhook Composio sends to your endpoint is signed with your subscription secret — verify it as described in Verifying webhooks.

Working with triggers

Configure delivery to your application. Create a webhook subscription so Composio knows which URL to deliver events to. One-time per project.

Configure ingress (only when needed). Use the schema endpoint to check whether your toolkit needs a manually-configured webhook endpoint; if it does, create one and point the provider's app dashboard at the URL Composio returns. One-time per OAuth app.

Discover available trigger types for the toolkit (e.g. GITHUB_COMMIT_EVENT).

Create an active trigger scoped to a user's connected account — see Creating triggers.

Receive events at your webhook subscription URL, verify the signature, and route on metadata.trigger_slug.

Manage triggers as needed — see Managing triggers.

Triggers are scoped to a connected account. If you haven't set up authentication yet, see Authentication.

Next steps

Creating triggers

Configure the webhook endpoint (when needed), then create trigger instances via the dashboard or SDK

Subscribing to events

Receive trigger events via webhooks or SDK subscriptions

Verifying webhooks

Verify webhook signatures and understand payload versions

Managing triggers

Discover, list, enable, disable, and delete triggers

Example: Gmail labeler

Build an automated email labeling agent using triggers

On this page

Two delivery typesWebhook endpointsChecking which case applies to your toolkitEnd-to-end flowWorking with triggersNext steps