Webhook Examples

WhatsApp Webhook Examples

Webhooks notify your application about real-time WhatsApp events. Configure webhook URLs in your session config, then route events to AI agents, CRMs, support desks, databases, monitoring systems, and n8n workflows.

Area	Events
Sessions	session.status
Messages	message, message.any, message.reaction, message.ack, message.waiting, message.edited, message.revoked
Chats and groups	chat.archive, group.v2.join, group.v2.leave, group.v2.participants, group.v2.update
Presence	presence.update
Polls and events	poll.vote, poll.vote.failed, event.response, event.response.failed
Labels and calls	label.upsert, label.deleted, label.chat.added, label.chat.deleted, call.received, call.accepted, call.rejected

message

Fired on incoming messages such as text, audio, images, videos, and files. Use it to trigger support triage, AI replies, CRM lookup, or sales handoff.

{
  "event": "message",
  "session": "default",
  "payload": {
    "id": "[email protected]_AAAA...",
    "timestamp": 1667561485,
    "from": "[email protected]",
    "fromMe": false,
    "source": "app",
    "to": "[email protected]",
    "body": "I need help with my invoice",
    "hasMedia": false,
    "ack": 1
  }
}

session.status

Fired when a session changes state. Use it to alert admins when a WhatsApp account needs reconnect or QR scanning.

{
  "event": "session.status",
  "session": "default",
  "payload": {
    "status": "WORKING",
    "statuses": [
      { "status": "STOPPED", "timestamp": 1700000001000 },
      { "status": "STARTING", "timestamp": 1700000002000 },
      { "status": "WORKING", "timestamp": 1700000003000 }
    ]
  }
}

message.ack

Fired when a message status changes: pending, sent, delivered, read, or played.

{
  "event": "message.ack",
  "session": "default",
  "payload": {
    "id": "[email protected]_...",
    "from": "[email protected]",
    "participant": null,
    "fromMe": true,
    "ack": 3,
    "ackName": "READ"
  }
}

group.v2.participants

Fired when group participants join, leave, promote, or demote. Useful for operations, field teams, communities, and monitoring groups.

{
  "event": "group.v2.participants",
  "payload": {
    "type": "join",
    "group": { "id": "[email protected]" },
    "participants": [{ "id": "[email protected]", "role": "participant" }]
  }
}

poll.vote

Fired when a poll vote is processed. Use it for lightweight approvals, menus, routing, or feedback flows.

{
  "event": "poll.vote",
  "payload": {
    "vote": {
      "id": "[email protected]_...",
      "from": "[email protected]",
      "fromMe": false,
      "selectedOptions": ["Awesome!"],
      "timestamp": 1692861427
    },
    "poll": { "id": "[email protected]_..." }
  }
}

event.response

Fired when a user responds to a calendar event message.

{
  "event": "event.response",
  "payload": {
    "eventResponse": {
      "response": "GOING",
      "timestampMs": 1747707858429,
      "extraGuestCount": 0
    }
  }
}

label.upsert

Fired when a WhatsApp Business label is created or updated.

{
  "event": "label.upsert",
  "payload": {
    "id": "10",
    "name": "Label Name",
    "color": 14,
    "colorHex": "#00a0f2"
  }
}

call.received

Fired when an incoming call is received.

{
  "event": "call.received",
  "session": "default",
  "payload": {
    "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "from": "[email protected]",
    "timestamp": 1721374000,
    "isVideo": false,
    "isGroup": false
  }
}