Triggers
When events occur in apps — a new Slack message, a GitHub commit, an incoming email — triggers send event data to your application as structured payloads.
Two delivery types
| Type | What happens | Examples |
|---|---|---|
| Webhook | The provider pushes 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, ... |
| Polling | Composio 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.
Setup at a glance
Two pieces of setup, both one-time:
| Piece | When it's needed | Scope | Where it's documented |
|---|---|---|---|
| Webhook subscription — your URL where Composio delivers signed events | Always | Once per project | Subscribing to triggers |
| Webhook endpoint — the URL the provider posts events to | Only when the trigger type requires it | Once per OAuth app | Configuring the webhook endpoint |
Whether a webhook endpoint needs to be configured is a property of the trigger type itself — composio.triggers.get_type() exposes a requires_webhook_endpoint flag, and the trigger creation call returns a 400 if the flag is true and no endpoint exists yet.
For Composio-managed OAuth apps the flag is always false — endpoints are pre-provisioned and you never configure them. With your own OAuth app it depends on the trigger.
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 endpointTwo webhook URLs sit on opposite sides of Composio. Don't confuse them:
| URL | Direction | Who configures it |
|---|---|---|
Ingress (/api/v3.1/webhook_ingress/...) | Provider → Composio | Composio in most cases; you when the trigger type's requires_webhook_endpoint flag is true — see Configuring the webhook endpoint |
| Webhook subscription (your URL) | Composio → your application | You, 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.
Pick a trigger type and inspect it. Find the trigger type for the event you want (e.g. GITHUB_COMMIT_EVENT) and inspect it — the response tells you what config it needs and whether a webhook endpoint must be configured first.
If the trigger requires a webhook endpoint, configure it. Follow Configuring the webhook endpoint. One-time per OAuth app.
Create the trigger scoped to a user's connected account — see Creating triggers.
Receive events at your 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
Inspect a trigger type, configure the webhook endpoint when required, then create trigger instances
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