Webhook Events | ActiWAPI

Subscribe to HTTPS endpoints and receive real-time notifications for sessions and messages. List available events with GET /api/webhooks/events (no auth).

Delivery headers

X-Webhook-Event — canonical event name
X-Webhook-Signature — HMAC-SHA256 of the JSON body
X-Webhook-Delivery-Id — unique delivery UUID
X-Webhook-Attempt — retry attempt number

session_connectedsessions

Fired when a WhatsApp session successfully connects.

{
  "event": "session_connected",
  "timestamp": "2026-01-01T12:00:00.000Z",
  "data": {
    "sessionId": "uuid",
    "phone": "+15551234567",
    "status": "connected"
  }
}

session_disconnectedsessions

Fired when a WhatsApp session disconnects or logs out.

{
  "event": "session_disconnected",
  "timestamp": "2026-01-01T12:00:00.000Z",
  "data": {
    "sessionId": "uuid",
    "reason": "logged_out"
  }
}

message_receivedmessages

Inbound message from a contact.

{
  "event": "message_received",
  "timestamp": "2026-01-01T12:00:00.000Z",
  "data": {
    "sessionId": "uuid",
    "from": "+15551234567",
    "text": "Hello",
    "messageId": "msg-id"
  }
}

message_sentmessages

Outbound message accepted for delivery.

{
  "event": "message_sent",
  "timestamp": "2026-01-01T12:00:00.000Z",
  "data": {
    "sessionId": "uuid",
    "to": "+15551234567",
    "messageId": "msg-id"
  }
}

message_deliveredmessages

Delivery receipt for an outbound message.

{
  "event": "message_delivered",
  "timestamp": "2026-01-01T12:00:00.000Z",
  "data": {
    "sessionId": "uuid",
    "messageId": "msg-id",
    "deliveredAt": "2026-01-01T12:00:00.000Z"
  }
}

message_readmessages

Read receipt for an outbound message.

{
  "event": "message_read",
  "timestamp": "2026-01-01T12:00:00.000Z",
  "data": {
    "sessionId": "uuid",
    "messageId": "msg-id",
    "readAt": "2026-01-01T12:00:00.000Z"
  }
}