Payloads

Payload format

All webhooks send a POST request with this JSON structure:

{
  "data": { ... },
  "entity": "messages" | "conversations",
  "action": "insert" | "update"
}

The data field contains the full database row for the entity.

Examples

New incoming message

Event: messages / insert

{
  "data": {
    "id": "a4a8f56f-4570-47e2-bc2a-2f0d7db288b1",
    "conversation_id": "c9e2f1a3-8b7d-4e5f-a123-456789abcdef",
    "organization_id": "00438702-d4a3-4411-9141-21febf13acbb",
    "direction": "incoming",
    "content": {
      "type": "text",
      "text": { "body": "Hello!" }
    },
    "status": {
      "pending": "2026-05-06T03:39:23+00:00"
    },
    "wa_id": "wamid.HBgN...",
    "from": "5215588392274",
    "created_at": "2026-05-06T03:39:23+00:00",
    "updated_at": "2026-05-06T03:39:23+00:00"
  },
  "entity": "messages",
  "action": "insert"
}

Outgoing message sent by AI agent

Event: messages / insert

{
  "data": {
    "id": "b5b9f67g-5681-58f3-cd3b-3g1e8ec399c2",
    "conversation_id": "c9e2f1a3-8b7d-4e5f-a123-456789abcdef",
    "organization_id": "00438702-d4a3-4411-9141-21febf13acbb",
    "direction": "outgoing",
    "agent_id": "d7c1e234-...",
    "content": {
      "type": "text",
      "text": { "body": "Hi! How can I help you today?" }
    },
    "status": {
      "pending": "2026-05-06T03:39:25+00:00"
    },
    "created_at": "2026-05-06T03:39:25+00:00"
  },
  "entity": "messages",
  "action": "insert"
}

Message delivered and read

Event: messages / update

{
  "data": {
    "id": "b5b9f67g-5681-58f3-cd3b-3g1e8ec399c2",
    "status": {
      "pending": "2026-05-06T03:39:25+00:00",
      "sent": "2026-05-06T03:39:26+00:00",
      "delivered": "2026-05-06T03:39:27+00:00",
      "read": "2026-05-06T03:39:35+00:00"
    },
    "updated_at": "2026-05-06T03:39:35+00:00"
  },
  "entity": "messages",
  "action": "update"
}

New conversation

Event: conversations / insert

{
  "data": {
    "id": "c9e2f1a3-8b7d-4e5f-a123-456789abcdef",
    "organization_id": "00438702-d4a3-4411-9141-21febf13acbb",
    "organization_address": "375446602312881",
    "contact_address": "5215588392274",
    "service": "whatsapp",
    "status": "open",
    "created_at": "2026-05-06T03:39:23+00:00",
    "updated_at": "2026-05-06T03:39:23+00:00"
  },
  "entity": "conversations",
  "action": "insert"
}

Conversation closed

Event: conversations / update

{
  "data": {
    "id": "c9e2f1a3-8b7d-4e5f-a123-456789abcdef",
    "status": "closed",
    "updated_at": "2026-05-07T03:39:23+00:00"
  },
  "entity": "conversations",
  "action": "update"
}