Webhooks

When something happens in your account (a customer writes, a conversation is handed to your team, an appointment is booked) we send a POST with a JSON body to every endpoint subscribed to that event. Webhooks are part of the Business plan; an Owner or Admin sets them up under Integrations → Webhooks.

The envelopeCopy Anchor Link

Every event has the same outer shape. data depends on type; each event page documents it.

{
  "id": "evt_5dabddce7c097ab703f21e8fdf0ab52b",
  "type": "message.received",
  "apiVersion": "2026-10",
  "createdAt": "2026-10-01T09:30:05+00:00",
  "test": false,
  "company": {
    "id": "0b3d6f2e-8a41-4c75-9e20-5f7a1c3d9b84",
    "name": "متجر الرياض"
  },
  "data": {
    "conversation": {
      "id": "WhatsApp_3f6a2d18-0b7c-4e91-8a5d-c24e1f9b7a60",
      "channelId": "7c1e4b2a-9d3f-4e58-a6b1-2f0c8d7e5a13",
      "channelType": "whatsapp"
    },
    "contact": {
      "id": "3f6a2d18-0b7c-4e91-8a5d-c24e1f9b7a60",
      "name": "نورة العتيبي",
      "phone": "+966501234567",
      "whatsAppId": "966501234567"
    },
    "message": {
      "id": "m_wamid.HBgMOTY2NTAxMjM0NTY3FQIAEhggQTNFQjU2RkQ5RTcyOEIyRDQ1",
      "text": "السلام عليكم، متى يوصل طلبي رقم 10482؟",
      "type": "text",
      "receivedAt": "2026-10-01T09:30:00+00:00"
    }
  }
}

HeadersCopy Anchor Link

DeliveryCopy Anchor Link

• Answer with any 2xx within 10 seconds. Acknowledge first, then do the work: a receiver that holds the request open while it calls other systems will time out. Anything else (another status, a redirect, a timeout, a refused connection) is a failure and is retried.
• At least once. An event can arrive more than once, for example when your 2xx was lost on the way back. Every delivery of it carries the same id; record the ids you have handled and skip repeats.
• No ordering guarantee. Deliveries are sent in parallel and retried on a schedule, so a later event can arrive before an earlier one. Order by createdAt, and do not assume, for example, that conversation.started arrives before the first message.received.
• Verify before you trust. Check the signature and its timestamp on every request; see Verify webhook signatures.

When nothing is sentCopy Anchor Link

• Switched-off endpoints receive nothing; events that happen while an endpoint is off are not sent to it later.
• Outside the Business plan, endpoints are kept but receive nothing until the account is back on it.
• A pause on our side. We can pause all calls to merchants' systems, for example during an incident. The Webhooks page then shows a notice; events that happen during a pause are not sent later, and tests and resends are refused until it ends.

EventsCopy Anchor Link