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

An endpoint is configured in one of two ways:

ConfigurationWhen it appliesWhat you do
Composio configures it for youYou're using a Composio-managed OAuth app, or your own OAuth app on a toolkit where Composio can register webhooks on your behalf using the connected user's credentials (e.g. Asana)Nothing. Composio handles endpoint setup, signature verification, and provider-side registration when you create the trigger.
You configure itYou're using your own OAuth app on a toolkit where the provider posts events at the OAuth-app level — today Slack and Notion, with more toolkits moving to this flow over timeSet up the webhook endpoint once per OAuth app before you create any 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 or absent → 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, and so on. Today this applies to Slack and Notion; more toolkits will adopt this flow over time.

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 in most cases; you when you bring your own OAuth app on a toolkit like Slack or 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. When Composio configures the endpoint, the signing secret comes from the connected account's credentials; when 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 if your toolkit needs it. Use the schema endpoint to check. If it returns setup fields, create the webhook endpoint and paste the URL Composio returns into the provider's app dashboard. 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 if your toolkit needs it, 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