Webhook event types reference

Complete list of events you can subscribe to and their payload formats.

Message events

message.incoming

Fired when a customer sends you a message.

{
  "event": "message.incoming",
  "timestamp": "2026-05-29T10:30:00Z",
  "data": {
    "message_id": "wamid.HBgLOTE5ODc2...",
    "from": "+919876543210",
    "contact_id": "uuid",
    "contact_name": "John Doe",
    "type": "text",
    "text": "Hello, I need help",
    "whatsapp_account_id": "uuid"
  }
}

message.sent

Fired when your message is sent to WhatsApp.

{
  "event": "message.sent",
  "timestamp": "2026-05-29T10:30:05Z",
  "data": {
    "message_id": "wamid.HBgLOTE5ODc2...",
    "to": "+919876543210",
    "type": "text",
    "status": "sent"
  }
}

message.delivered

Fired when message reaches the recipient's phone.

message.read

Fired when recipient opens and reads the message.

message.failed

Fired when message delivery fails.

{
  "event": "message.failed",
  "data": {
    "message_id": "wamid.xxx",
    "to": "+919876543210",
    "error_code": 131047,
    "error_message": "Re-engagement message"
  }
}

Contact events

contact.created

{
  "event": "contact.created",
  "data": {
    "id": "uuid",
    "phone_number": "+919876543210",
    "name": "John Doe",
    "source": "whatsapp_webhook"
  }
}

contact.updated

Fired when contact data changes (name, tags, stage, custom fields).

Campaign events

campaign.completed

{
  "event": "campaign.completed",
  "data": {
    "id": "uuid",
    "name": "May Promotion",
    "total": 1000,
    "sent": 985,
    "delivered": 970,
    "read": 650,
    "failed": 15
  }
}

Transfer events

transfer.created

Fired when a conversation is transferred to an agent.

{
  "event": "transfer.created",
  "data": {
    "contact_id": "uuid",
    "from_agent_id": null,
    "to_agent_id": "uuid",
    "to_team_id": "uuid",
    "notes": "Customer asking about refund"
  }
}

Tips for handling events

1. Respond with 200 immediately — Process async
2. Use message_id for dedup — Same event may arrive twice
3. Filter by event type — Only subscribe to what you need
4. Log raw payloads — Helpful for debugging
5. Handle unknown events gracefully — New events may be added