webhooks.md


title: "WhatsApp webhooks" description: "The WhatsApp webhook events Bird can push to your endpoint, the envelope every one arrives in, and the fields a message event always carries." canonical: "https://bird.com/docs/guides/whatsapp/webhooks"

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.

Events you can subscribe to

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.

{
  "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, and to. The reaction, suppression, and group events are not about a message, so each has its own shape, given on its page.

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

Next steps