## 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

1. Generate an access token in settings.
2. Include the token in the auth header of your API calls.
3. Make requests to API resources (e.g., list contacts, create a conversation).
4. Configure a webhook with the URL and the events you want.
5. 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-Delivery` header 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](/hc/ajuda/articles/api-developers-eventos-por-modulo-en).

## 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.

## See also

- [Dashboard Apps SDK, REST API and MCP](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-en)
- [API & Developers overview](/hc/ajuda/articles/api-developers-overview-en)
- [Per-module events](/hc/ajuda/articles/api-developers-eventos-por-modulo-en)
- [API reference (Swagger / OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-en)