> ## Documentation Index > Fetch the complete documentation index at: https://docs.automatebusiness.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Subscribe to real-time events from Automate Chats to integrate with your custom CRM or automation workflows. Webhooks let you receive real-time HTTP POST notifications when events happen in your Automate Chats workspace. You can use webhooks to update external CRMs, trigger custom alerts, or automate complex business workflows. ## Delivery semantics Automate Chats delivers webhook events with the following constraints: * **Protocol**: HTTP `POST` requests sending JSON payloads. * **Delivery**: Best-effort single attempt. The system does not retry failed deliveries. * **Timeout**: The server waits a maximum of 5 seconds for a response. * **Payload size limit**: The maximum payload size is 256 KB. * **Status codes**: Your server must return a `2xx` HTTP status code to acknowledge receipt. ## Headers sent Every webhook request includes the following custom HTTP headers: * `Content-Type`: `application/json` * `X-Webhook-Id`: The unique ID of the configured webhook. * `X-Workspace-Id`: The ID of your Automate Chats workspace. * `X-Event-Key`: The event key that triggered this request. *** ## Supported events Configure your webhook to listen for the following events: ### Message events * `incoming`: Triggered when you receive an inbound WhatsApp message from a customer. This saves the message, updates the conversation, and starts chatbot or AI assistant sessions if active. * `sent`: Triggered when an outbound message is successfully sent and accepted by WhatsApp/Meta. This also records billing and pricing details in our system. * `delivered`: Triggered when Meta confirms the customer's device received the message. * `read`: Triggered when the customer reads your message. * `failed`: Triggered when an outbound message fails to deliver (e.g., number not on WhatsApp, expired 24h conversation window). ### Template events * `template`: Triggered when a WhatsApp message template status or category changes (e.g., when Meta approves or rejects a template, or modifies its category). This updates your local template records and notifies your team. ### Contact events * `contact.created`: Triggered when a new contact is registered in your workspace (manually, via CSV import, or automatically when a new customer sends an inbound message). * `contact.updated`: Triggered when contact details are edited or when a soft-deleted contact is restored. ### Conversation events * `conversation.assigned`: Triggered when a conversation is assigned to an agent or a team (manually, via chatbots, or by the AI assistant). * `conversation.status_changed`: Triggered when a conversation status changes (e.g., marked open, resolved, or closed, which also exits any active chatbot sessions). *** ## General payload structure Each webhook payload uses a standard JSON envelope: ```json theme={null} { "eventKey": "incoming", "workspaceId": 12, "timestamp": "2026-06-19T15:08:15.000Z", "data": { // Event-specific details } } ``` ### Event payloads ```json incoming (Message Received) theme={null} { "eventKey": "incoming", "workspaceId": 12, "timestamp": "2026-06-19T15:08:15.000Z", "data": { "message": { "id": "wamid.HBgLOTExMjIzMzQ0NTUVAgISFjNFMDk2QTk4OTk5QzAxRDQyQQA=", "from": "19876543210", "timestamp": "1718809695", "type": "text", "text": { "body": "Hello, I need help with my order." } }, "phoneNumberId": "105672839485761", "metaEvent": { "object": "whatsapp_business_account", "entry": [ { "id": "105672839485760", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "1122334455", "phone_number_id": "105672839485761" }, "contacts": [ { "profile": { "name": "Jane Doe" }, "wa_id": "19876543210" } ], "messages": [ { "from": "19876543210", "id": "wamid.HBgLOTExMjIzMzQ0NTUVAgISFjNFMDk2QTk4OTk5QzAxRDQyQQA=", "timestamp": "1718809695", "text": { "body": "Hello, I need help with my order." }, "type": "text" } ] }, "field": "messages" } ] } ] } } } ``` ```json sent / delivered / read / failed theme={null} { "eventKey": "sent", "workspaceId": 12, "timestamp": "2026-06-19T15:08:15.000Z", "data": { "status": { "id": "wamid.HBgLOTExMjIzMzQ0NTUVAgISFjNFMDk2QTk4OTk5QzAxRDQyQQA=", "status": "sent", "timestamp": "1718809696", "recipient_id": "19876543210", "pricing": { "billable": true, "pricing_model": "CBP", "category": "utility" } }, "phoneNumberId": "105672839485761", "messageSource": "inbox", "metaEvent": { "statuses": [ { "id": "wamid.HBgLOTExMjIzMzQ0NTUVAgISFjNFMDk2QTk4OTk5QzAxRDQyQQA=", "status": "sent", "timestamp": "1718809696", "recipient_id": "19876543210", "pricing": { "billable": true, "pricing_model": "CBP", "category": "utility" } } ] } } } ``` ```json template (Status Update) theme={null} { "eventKey": "template", "workspaceId": 12, "timestamp": "2026-06-19T15:08:15.000Z", "data": { "type": "status", "metaTemplateId": "736481928374910", "newStatus": "APPROVED", "name": "order_delivery_update", "language": "en_US", "reason": null, "template": { "id": "507f1f77bcf86cd799439011", "name": "order_delivery_update", "language": "en_US", "meta_template_id": "736481928374910", "meta_template_status": "APPROVED" } } } ``` ```json contact.created / contact.updated theme={null} { "eventKey": "contact.created", "workspaceId": 12, "timestamp": "2026-06-19T15:08:15.000Z", "data": { "contact": { "id": "607f1f77bcf86cd799439022", "firstName": "Jane", "lastName": "Doe", "chatName": "Jane Doe", "email": "jane.doe@example.com", "phoneNumber": "9876543210", "countryCode": "91", "source": "whatsapp", "subscribed": true, "customFields": [ { "fieldId": "507f1f77bcf86cd799439001", "value": "Gold Member" } ], "tagsId": [ "507f1f77bcf86cd799439002" ], "dob": "1990-01-15T00:00:00.000Z", "createdAt": "2026-06-19T15:08:15.000Z", "updatedAt": "2026-06-19T15:08:15.000Z" } } } ``` ```json conversation.assigned theme={null} { "eventKey": "conversation.assigned", "workspaceId": 12, "timestamp": "2026-06-19T15:08:15.000Z", "data": { "conversationId": "607f1f77bcf86cd799439033", "channelId": "507f1f77bcf86cd799439004", "phoneNumberId": "105672839485761", "contactId": "607f1f77bcf86cd799439022", "assignmentType": "user", "assignedTo": { "id": "usr_92837492", "name": "Alex Agent", "firstName": "Alex", "lastName": "Agent", "email": "alex@automatebusiness.com" }, "assignedBy": { "id": "usr_10293847", "name": "Admin User", "email": "admin@automatebusiness.com" }, "chatMode": "user", "source": "manual" } } ``` ```json conversation.status_changed theme={null} { "eventKey": "conversation.status_changed", "workspaceId": 12, "timestamp": "2026-06-19T15:08:15.000Z", "data": { "conversationId": "607f1f77bcf86cd799439033", "channelId": "507f1f77bcf86cd799439004", "phoneNumberId": "105672839485761", "contactId": "607f1f77bcf86cd799439022", "previousStatus": "open", "newStatus": "closed", "closedAt": "2026-06-19T15:08:15.000Z", "changedBy": { "id": "usr_10293847", "name": "Admin User", "email": "admin@automatebusiness.com" } } } ``` *** ## API reference Configure and manage your webhooks using the `/external-webhooks` endpoints. You must authorize all API calls using your workspace key in the `X-API-Key` header. ### Create a webhook Register a new webhook URL and select the events you wish to receive. * **HTTP Method**: `POST` * **Path**: `/api/external-webhooks` #### Request body | Field | Type | Description | | :------- | :------- | :-------------------------------------------------------------- | | `title` | `string` | A descriptive name for the webhook. | | `url` | `string` | The target HTTP/HTTPS URL that will receive the payloads. | | `status` | `string` | Set to `"active"` or `"inactive"`. | | `events` | `array` | A list of event keys (e.g., `["incoming", "failed"]`). | | `secret` | `string` | *(Optional)* A custom secret token to verify payload integrity. | #### Request example ```bash theme={null} curl --request POST \ --url https://api.automatechats.com/api/external-webhooks \ --header 'Content-Type: application/json' \ --header 'X-API-Key: YOUR_API_KEY' \ --data '{ "title": "Customer Support CRM Webhook", "url": "https://crm.mycompany.com/webhooks/whatsapp", "status": "active", "events": ["incoming", "failed", "conversation.status_changed"], "secret": "my-shared-webhook-secret" }' ``` *** ### List webhooks Retrieve a list of webhooks configured for your workspace. * **HTTP Method**: `GET` * **Path**: `/api/external-webhooks` #### Query parameters | Parameter | Type | Description | | :-------- | :-------- | :------------------------------------------------------------------ | | `page` | `integer` | *(Optional)* Page number for pagination. Default is `1`. | | `limit` | `integer` | *(Optional)* Number of records per page (max 100). Default is `10`. | #### Request example ```bash theme={null} curl --request GET \ --url 'https://api.automatechats.com/api/external-webhooks?page=1&limit=10' \ --header 'X-API-Key: YOUR_API_KEY' ``` *** ### Update a webhook Modify an existing webhook's subscription events, target URL, status, or secret. * **HTTP Method**: `PATCH` * **Path**: `/api/external-webhooks/:id` #### Request example ```bash theme={null} curl --request PATCH \ --url https://api.automatechats.com/api/external-webhooks/607f1f77bcf86cd799439011 \ --header 'Content-Type: application/json' \ --header 'X-API-Key: YOUR_API_KEY' \ --data '{ "url": "https://crm.mycompany.com/webhooks/whatsapp-updated", "events": ["incoming", "delivered", "failed"] }' ``` *** ### Delete a webhook Remove a webhook configuration from your workspace. * **HTTP Method**: `DELETE` * **Path**: `/api/external-webhooks/:id` #### Request example ```bash theme={null} curl --request DELETE \ --url https://api.automatechats.com/api/external-webhooks/607f1f77bcf86cd799439011 \ --header 'X-API-Key: YOUR_API_KEY' ```