Triggers
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.
Three delivery models
Every Composio trigger fits one of three delivery models. The model is a property of the trigger type, not something you choose — but knowing which model your trigger uses tells you exactly what setup is required.
| Delivery model | What Composio does | What you do |
|---|---|---|
| Polling | Composio polls the provider on a schedule (15-minute minimum on Composio managed auth) | Just create the trigger |
| User-level webhook | Composio registers a per-user webhook with the provider when you create the trigger, and deregisters it when you delete the trigger | Just create the trigger |
| App-level webhook endpoint | Composio gives you one ingress URL per OAuth app; you point the provider's app dashboard at it once | Configure a webhook endpoint for the OAuth app, then create triggers normally |
End-to-end flow
For every trigger, regardless of delivery model, events take the same path on the way to your application:
provider event ──▶ Composio ingress ──▶ trigger fan-out ──▶ webhook subscription ──▶ your endpointTwo webhook URLs sit on opposite sides of Composio. Don't confuse them:
| URL | Direction | Who configures it |
|---|---|---|
Ingress (/api/v3.1/trigger_instances/.../handle for V1, /api/v3.1/webhook_ingress/... for V2) | Provider → Composio | Composio (V1, automatic) or you, once per OAuth app (V2 — see Configuring webhook endpoints) |
| Webhook subscription (your URL) | Composio → your application | You, once per project — see Subscribing to triggers |
Composio verifies signatures on both hops:
- On ingress, V2 endpoints verify the provider's signature against the signing secret you stored on the endpoint. Unsigned or tampered requests are rejected before any trigger fires.
- On 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. This is a one-time step per project.
Configure ingress (V2 toolkits only). For toolkits on V2 (currently Slack), create a webhook endpoint and point the provider's app dashboard at the URL Composio returns. One-time per OAuth app.
Discover available trigger types for a 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
Create trigger instances via the dashboard or SDK
Configuring webhook endpoints
One-time setup for V2 toolkits like Slack: create an ingress URL, store the signing secret, point the provider at it
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