requires_webhook_endpoint_setup flag is true.
Each OAuth app you bring gets its own ingress URL within a project:
- Its own ingress rate limit and backpressure budget
- Project-scoped credentials: the signing secret and app-level token you provide are stored against this project alone, never shared across projects. Repeat verification handshakes are rejected after the endpoint is verified, so the signing secret can’t be silently swapped by a forged challenge.
- Clean fan-out: events reach only that project’s trigger instances
- Per-project metering
- HMAC-SHA256 for Slack, Ed25519 or shared-token matching for other providers
- Timestamp replay protection: when the provider signs a request timestamp, requests outside the allowed skew window are rejected
- Unsigned or tampered requests are rejected with
400at ingress, so third parties can’t spoof events onto your triggers
composio.webhooks.endpoints in either SDK. Use list() and get() to inspect endpoints, create() to register one, and replace() or update() to change its configuration.
The walkthrough below uses Slack as the example and the Webhook Endpoints API. For setup notes specific to each toolkit, see its FAQ section, for example Slack or Notion.
Step 1: Collect the provider credentials
For Slack, collect the Signing Secret from your app’s Basic Information page and an App-Level Token (xapp-...) with the authorizations:read scope. Keep both secret. The endpoint verification step below uses webhook_signing_secret and app_token; it does not require a separate Composio schema-discovery request.
Use the Webhook Endpoints API for the supported create, retrieve, replace, and update operations. The committed API contract does not declare /webhook_endpoints/schema.
Step 2: Create the endpoint
- Python
- TypeScript
- API
id (we_abc123 in the examples below) and webhook_url (you’ll paste this into the provider’s app dashboard in step 4). The call is idempotent per (toolkit_slug, client_id) within a project. Calling it again with the same pair returns the existing endpoint without rotating the URL or wiping the secret.
Step 3: Store the credentials returned by the schema
PATCH all the fields the schema returned in a single request. For Slack, that’s the signing secret and (when needed) the app-level token together:
- Python
- TypeScript
- API
- Signing secret: Slack app → Basic Information → App Credentials → Signing Secret.
- App-level token: Slack app → Basic Information → App-Level Tokens, with scope
authorizations:read. Required for direct messages, private channels, and reactions. Omit it if you only need public-channel events.
Step 4: Point the provider’s app dashboard at the URL
Paste thewebhook_url from step 2 into the provider’s app dashboard:
- Slack → Event Subscriptions → Request URL
- Notion → Webhook Endpoints (in the integration’s settings)
url_verification, Notion’s verification token, and so on), Composio responds automatically, with no handshake code on your side. Once the provider accepts the URL, go create your trigger.
Updating an endpoint
To rotate the signing secret or update any single field,PATCH it (other fields are preserved):
- Python
- TypeScript
- API
data wholesale (any field you don’t include is cleared), POST to the same URL:
- Python
- TypeScript
- API
webhook_url is immutable for the lifetime of the endpoint. Rotating the signing secret on the provider side is a PATCH on the existing endpoint, not a new one.
To inspect a single endpoint:
- Python
- TypeScript
- API
- Python
- TypeScript
- API