Overview
The REST API lets you read and write platform data (contacts, conversations, messages and more). Authentication uses an access token, and webhooks deliver events to your system in real time.
Prerequisites
- A valid access token.
- An HTTPS endpoint to receive webhooks.
Step by step
- Generate an access token in settings.
- Include the token in the auth header of your API calls.
- Make requests to API resources (e.g., list contacts, create a conversation).
- Configure a webhook with the URL and the events you want.
- Validate the webhook signature/secret before processing the payload.
Settings & options
- Token scope: limit access to what's needed.
- Webhook events: subscribe only to the events you use.
- Signing secret: it is shown once, immediately after the webhook is created. Copy it and store it securely; list and edit responses only confirm that a secret is configured and never reveal it. If it is lost, create a replacement webhook and remove the old destination.
- Durable delivery: every account-webhook delivery is recorded before it is queued. Network errors and 5xx responses use backoff retries and remain visible in delivery history.
- History and replay: under Settings → Integrations → Webhooks, open a destination's history to search, filter, and sort attempts. An administrator can replay one or several rows; bulk results keep processed and failed IDs separate.
- Commerce payload: the default sends canonical identifiers only. Enable Include commerce details on a destination only when the receiver needs normalized buyer, product/variant, and sale items. The opt-in never adds credentials or a raw gateway payload.
- Receiver idempotency: use the
X-Chatwoot-Deliveryheader as the idempotency key; a manual replay reuses the same identifier.
Event catalog (module groups)
All events below are account-level subscriptions (configured per account, on the Webhooks screen). For a module to deliver its events, the module feature must be enabled on the account — the subscription is accepted even with the feature off, but nothing is delivered until you turn it on.
- Conversations, messages, contacts, inbox and typing — the support lifecycle.
- CRM (deals) — creation, stage, won/lost, priority, value, health, checklist, SLA and close dates.
- Catalog and Commerce — products, variants/stock and the Commerce payment cycle.
- Orders and revenue — order registration, status, paid, refunded, revenue and affiliates.
- Tasks, Calendar and bookings, Payments and Follow-ups — each module's lifecycle.
- Contracts and e-signature, Sales Management and Engagement/Lead Score.
- Account Brain — risk, insights, department runs and proposed improvements.
- Distribution (Launch Groups) — member enrollment, invitation, joining and unit completion.
- Growth Social and Ads — comments, ad leads, campaign status and the Click-to-WhatsApp window.
- WhatsApp Hub — broadcasts, participant events and group welcome/farewell greetings (Cloud and WazMeow).
- WhatsApp calls and Flow responses — call lifecycle and WhatsApp Flow responses.
- Team Management — agent status change, breaks and shifts.
- FlowBuilder — flow session lifecycle.
- Smart Routing — agent assignment.
The real fields for each payload are in Per-module events.
Use cases
- Mirror conversations into a data warehouse.
- Notify an external system when a conversation is created or resolved.
Tips, limits & best practices
- Always verify the webhook signature before acting.
- Ensure idempotency with
X-Chatwoot-Delivery, including retries and manual replays. - Respect rate limits and use backoff on 429/5xx errors.
Troubleshooting
- 401/403: invalid token or missing permission.
- Duplicate webhook: confirm the receiver deduplicates
X-Chatwoot-Delivery. - Failed delivery: open the destination history and inspect its HTTP status/error and next attempt. After fixing the receiver, select the row and confirm replay.