Webhook events and payloads

Events

Messages

Contacts

Flows

Broadcasts: broadcast.started, broadcast.completed, broadcast.failed
Templates: template.approved, template.rejected (with the reason)
Ads: ad_lead.received — someone messaged you from a Click-to-WhatsApp ad

Contact, template, broadcast, flow and ad-lead events fire however the change was made — the inbox, an import, an automation, the API or Meta.

The envelope

{
  "id": "evt_4f1c9a0b2e7d4c3a8b6e5f1d2c3b4a59",
  "type": "contact.tag_added",
  "workspace_id": "6b2f…",
  "created_at": "2026-09-14T10:30:00.000Z",
  "api_version": "2026-09-01",
  "data": { }
}

• id is unique and stable — a retry or resend has the same id. Store handled ids and skip repeats.
• Events can arrive more than once and out of order. Use created_at and your own dedupe.

data by event

// message.received
{ "conversation_id": "…", "contact_id": "…", "whatsapp_message_id": "wamid.…",
  "content_type": "text", "text": "Hi, is this still available?" }

// message.sent | message.delivered | message.read | message.failed
{ "whatsapp_message_id": "wamid.…", "conversation_id": "…",   // null for a broadcast send
  "contact_id": "…", "broadcast_id": null,                     // set for a broadcast send
  "status": "failed", "occurred_at": "2026-09-14T10:30:02.000Z",
  "error": { "code": 131026, "title": "Message undeliverable",   // message.failed only
             "message": "(#131026) Message undeliverable" } }

// contact.created | contact.opted_out
{ "contact": { "id": "…", "phone": "+14155550123", "name": "Asha", "email": null,
               "company": null, "opted_out": false, "opted_out_at": null,
               "created_at": "…", "updated_at": "…" },
  "source": "stop_keyword" }                                   // contact.opted_out only

// contact.updated
{ "contact": { … }, "changed": ["name", "email"] }

// contact.tag_added | contact.tag_removed
{ "contact": { … }, "tag": { "id": "…", "name": "Hot lead" } }

// flow.*
{ "flow_run": { "id": "…", "flow_id": "…", "contact_id": "…", "conversation_id": "…",
                "status": "handed_off", "node_key": "ask_budget", "end_reason": null,
                "started_at": "…", "ended_at": "…" } }

// broadcast.*
{ "broadcast": { "id": "…", "name": "Diwali offer", "template_name": "diwali_2026",
                 "status": "sent", "total_recipients": 1200, "sent_count": 1180,
                 "delivered_count": 1102, "read_count": 640, "failed_count": 20 } }

// template.approved | template.rejected
{ "template": { "id": "…", "name": "order_update", "language": "en_US",
                "category": "UTILITY", "status": "REJECTED",
                "rejection_reason": "INVALID_FORMAT" } }

// ad_lead.received
{ "contact": { … }, "conversation_id": "…",
  "referral": { "ctwa_clid": "ARAkL…", "source_id": "120211…", "source_type": "ad",
                "source_url": "https://fb.me/…", "headline": "Book a free demo",
                "body": "…", "media_type": "image" },
  "whatsapp_message_id": "wamid.…", "occurred_at": "…" }

source_id is the Meta ad ID and ctwa_clid is Meta’s click ID — present only when Ads attribution is on.

Headers