Skip to main content
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: 
{
  "eventKey": "incoming",
  "workspaceId": 12,
  "timestamp": "2026-06-19T15:08:15.000Z",
  "data": {
    // Event-specific details
  }
}

​
Event payloads

{
  "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"
            }
          ]
        }
      ]
    }
  }
}

{
  "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"
          }
        }
      ]
    }
  }
}

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

{
  "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"
  }
}

{
  "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

FieldTypeDescription
titlestringA descriptive name for the webhook.
urlstringThe target HTTP/HTTPS URL that will receive the payloads.
statusstringSet to "active" or "inactive".
eventsarrayA list of event keys (e.g., ["incoming", "failed"]).
secretstring(Optional) A custom secret token to verify payload integrity.

​
Request example

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

ParameterTypeDescription
pageinteger(Optional) Page number for pagination. Default is 1.
limitinteger(Optional) Number of records per page (max 100). Default is 10.

​
Request example

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

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

curl --request DELETE \
  --url https://api.automatechats.com/api/external-webhooks/607f1f77bcf86cd799439011 \
  --header 'X-API-Key: YOUR_API_KEY'