WhatsApp webhooks

Bird pushes WhatsApp activity to your endpoint as it happens, so you do not have to poll for it. Subscribe from the Webhooks page or with POST /v1/webhooks. The Webhooks guide covers endpoints, signature verification, and retries.

Each event links to its payload.

Event	Fires when
whatsapp.accepted	Bird accepts an outbound send request
whatsapp.sent	Bird hands the message to the WhatsApp network
whatsapp.delivered	WhatsApp confirms delivery to the recipient's device
whatsapp.read	The recipient opens the message
whatsapp.failed	The message fails to deliver
whatsapp.rejected	Bird refuses the message before sending it
whatsapp.received	A contact sends you a message
whatsapp.reacted	A contact adds, changes, or removes a reaction
whatsapp_suppression.created	A suppression opens on your workspace
whatsapp.group.join_request_created	Someone asks to join a group
whatsapp.group.join_request_revoked	Someone cancels their request to join a group

The event type list is open: new types may be added over time, so treat an unrecognized value as a future event rather than an error.

The event envelope

Every WhatsApp event uses the standard webhook envelope: a type, a timestamp, and a type-specific data object.

Codebeispiel

{
  "data": {
    "direction": "outbound",
    "from": { "phone_number": "+13124495569" },
    "metadata": { "session_id": "sess_4821" },
    "tags": [{ "name": "flow", "value": "login-otp" }],
    "to": { "phone_number": "+14155550100" },
    "whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:51:39.913Z",
  "type": "whatsapp.delivered"
}

Fields every message event carries

Each WhatsApp webhook payload for a message carries whatsapp_id, workspace_id, direction, from, to, tags, and metadata. The reaction, suppression, and group events are not about a message, so each has its own shape, given on its page.

Addresses: from and to can include an E.164 phone_number, a Meta business-scoped user ID in bsuid, or both. A message received from a WhatsApp user also carries the profile they publish, in username and display_name.
tags and metadata are null when the send carried none.
in_reply_to_message_id appears on every outbound event of a message sent in reply, from whatsapp.accepted through whatsapp.read, whatsapp.failed, or whatsapp.rejected, naming the message it answers.

Event payloads carry no cost. Read the message back with GET /v1/whatsapp/messages/{message_id} to see what it cost.

Next steps

Message lifecycle webhooks: delivery and incoming-message payloads
Lifecycle events: read the same timeline back through the API
Webhooks guide: endpoints, signatures, retries, and the full event catalog

WhatsApp webhooks

Events you can subscribe to

The event envelope

Fields every message event carries

Next steps

Verwandte Ressourcen