---

title: "Webhooks & events"
description: "Receive Bird events as signed HTTPS deliveries: endpoint setup, Standard Webhooks signature verification, retries, replay, and the event envelope."
canonical: "https://bird.com/docs/guides/webhooks"
---

# Webhooks & events

When something happens in your workspace (an email is delivered, a recipient bounces, a WhatsApp message is read), Bird POSTs a signed JSON event to every webhook endpoint subscribed to that event type. Bird follows the [Standard Webhooks](https://www.standardwebhooks.com) specification for headers, signing, and payload structure, so if you already verify webhooks from another Standard Webhooks platform, the same verification code works here unchanged.

For an overview of webhook endpoints and delivery, see [What is a webhook?](/explained/platform/what-is-a-webhook).

## Create an endpoint

Register an endpoint in the dashboard under **Platform tools** > [**Webhooks**](/content/dashboard/w/webhooks/index.html), or from the terminal with the [Bird CLI](/docs/cli):

```bash
bird webhooks create --url https://example.com/webhooks/bird \
  --events email.delivered,email.bounced,email.complained \
  --description "Production delivery + bounce notifications"
```

Endpoint management requires the `webhooks` scope. Dashboard sessions and the CLI's login carry it through your user role, and API keys can hold it too: grant `webhooks:read` to inspect endpoints and delivery attempts, or `webhooks:write` to manage them. The underlying operations start at [`POST /v1/webhooks`](/docs/api/reference/create-webhook).

Endpoint URLs must be HTTPS, at most 2048 characters, and publicly reachable. URLs on private, loopback, link-local, or otherwise internal addresses are rejected with a `422` when you create or update the endpoint. Deliveries originate from Bird's delivery infrastructure outside your network.

The `events` array lists up to 100 types from the [event catalog](#event-catalog). An endpoint receives only the types it lists. Use [`PATCH /v1/webhooks/{webhook_id}`](/docs/api/reference/update-webhook) to replace the complete list for future deliveries. To receive every event, subscribe to every type: a type outside the catalog is refused with a `422`, and that includes a wildcard such as `sms.*`. Existing subscriptions do not expand when new types become available.

The create response includes the endpoint's signing `secret` (prefixed `whsec_`) **exactly once**. Store it in your secret manager immediately; it cannot be retrieved again, and if you lose it, [rotate it](#rotating-the-signing-secret).

```json
{
  "id": "whk_01ky7q639cfh99xb7ysy2x2gzj",
  "url": "https://example.com/webhooks/bird",
  "events": ["email.delivered", "email.bounced", "email.complained"],
  "description": "Production delivery + bounce notifications",
  "status": "active",
  "secret": "whsec_c+dgRBsFELJ9mR4tu2cyhK0gTMMkqntv",
  "created_at": "2026-07-23T14:48:29.740Z",
  "updated_at": "2026-07-23T14:48:29.740Z"
}
```

Endpoints support full CRUD: [list](/docs/api/reference/list-webhooks), [get](/docs/api/reference/get-webhook), update, and [delete](/docs/api/reference/delete-webhook). Deleting an endpoint stops all deliveries to it, including retries of earlier failed deliveries, and cannot be undone; to stop deliveries temporarily, set `status` to `paused` instead. A workspace can register multiple endpoints, each with its own URL, event filter, and secret.

## Send events to a no-code tool or an agent platform

Any receiver that accepts an HTTPS POST works as a plain endpoint, including a Zapier "Catch Hook", a Make custom webhook, or an n8n Webhook node. Create the trigger in that tool, copy its URL, and register it as above. In n8n, use the workflow's production URL: the test URL only listens while the editor is waiting for a test event.

To have Claude Managed Agents or Grok Bot answer the messages you receive, follow [Route messages to your AI agent](/docs/ai/route-messages-to-an-agent) instead. An MCP client such as ChatGPT can subscribe to events itself through [MCP Events](/docs/ai/mcp-events). To score inbound messages before an agent acts on them, see [Superagent](/ai/superagent).

Before creating a plain endpoint, filter [`GET /v1/webhooks`](/docs/api/reference/list-webhooks) by `url` to find one a previous setup made, and change it with [`PATCH /v1/webhooks/{webhook_id}`](/docs/api/reference/update-webhook) instead of creating a second. Several endpoints can share a URL, so check a match's description and events before changing it. The filter only finds matches, it does not stop duplicates:

```bash
bird webhooks list --url https://hooks.zapier.com/hooks/catch/123/abc/
bird webhooks update whk_01krdgeqcxet5s7t44vh8rt9mg --events sms.received,whatsapp.received
```

Then [send a test event](#test-sends) to confirm the receiver accepts it.

### Set it up with an AI agent

The bird CLI and MCP server carry a `webhooks.setup` procedure that walks an agent through this flow: what to ask you (the receiver URL, the events, any credentials), finding an existing endpoint, creating one, and sending a test event before reporting success. Ask your agent to "send Bird's inbound SMS to my Zapier hook" and it follows the same steps.

## Verify signatures

Every delivery carries three headers:

| Header              | Value                                                                          |
| ------------------- | ------------------------------------------------------------------------------ |
| `webhook-id`        | Identifies the event delivery. Retries and replays of it reuse the same value. |
| `webhook-timestamp` | Unix timestamp (seconds) of this delivery attempt                              |
| `webhook-signature` | `v1,<base64 HMAC-SHA256>`, possibly several signatures space-delimited         |

The signature is an HMAC-SHA256 over the string `{webhook-id}.{webhook-timestamp}.{raw request body}`, keyed with your endpoint's secret (strip the `whsec_` prefix and base64-decode the remainder to get the key bytes). Your handler should verify the signature, reject deliveries whose `webhook-timestamp` is more than 5 minutes old, and deduplicate on `webhook-id`: Bird delivers at-least-once, so the same delivery can arrive more than once.

With the [Bird SDK](/docs/sdks/typescript), the signature and timestamp checks are one call; deduplication stays in your handler:

**TypeScript**

```typescript
// Pass the RAW request body; set the secret via new BirdClient({ webhooks: { secret } }).
const event = bird.webhooks.unwrap(rawBody, headers);
console.log(event.type); // discriminated union: narrow on event.type
```

Examples: [TypeScript](/docs/guides/webhooks.ts.md) · [Python](/docs/guides/webhooks.py.md) · [Go](/docs/guides/webhooks.go.md) · [PHP](/docs/guides/webhooks.php.md)

Rejecting a delivery with `400`, as the examples above do, does not discard the event: we retry it on the [schedule below](#delivery-semantics). That is deliberate, and it is what you want. The usual cause of a failed verification is a secret your handler does not have yet, during a [rotation](#rotating-the-signing-secret) or a bad deploy, so the retry window is your chance to fix the secret and still receive the event. Return `2xx` only when you mean to discard the delivery for good.

Any [Standard Webhooks reference library](https://www.standardwebhooks.com) works too. If you verify by hand, the recipe is:

```typescript
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, headers: Record<string, string>, secret: string): boolean {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // 5-minute tolerance

const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest("base64");

// During secret rotation, the header can contain several signatures. Accept any match.
  return headers["webhook-signature"].split(" ").some((part) => {
    const sig = Buffer.from(part.replace(/^v1,/, ""), "base64");
    return (
      sig.length === Buffer.byteLength(expected, "base64") &&
      timingSafeEqual(sig, Buffer.from(expected, "base64"))
    );
  });
}
```

Always compute the HMAC over the **raw request body bytes**. Parsing and re-serializing the JSON changes whitespace or key order and breaks the signature.

To also authenticate deliveries in the TLS handshake, set up a [webhook client certificate](/docs/guides/mtls#present-a-client-certificate-on-webhook-deliveries).

## Delivery semantics

Each delivery is one event per HTTP POST with `Content-Type: application/json`, no batching. Your endpoint has **15 seconds** to respond; any `2xx` status counts as success, and anything else (including `3xx` redirects and timeouts) counts as a failure. Every failure follows the same retry schedule. The status you return changes what you see in the delivery attempts log, not whether we retry: there is no status code that stops delivery early. Respond quickly and process asynchronously: queue the event and return `200` before doing real work.

After the first attempt, failed deliveries are retried on this schedule, with ±20% jitter so retries don't synchronize:

| Retry | Delay after the previous attempt |
| ----- | -------------------------------- |
| 1     | 5 seconds                        |
| 2     | 5 minutes                        |
| 3     | 30 minutes                       |
| 4     | 2 hours                          |
| 5     | 5 hours                          |
| 6     | 10 hours                         |
| 7     | 10 hours                         |
|
That's eight attempts over roughly 27.5 hours. A `429` or timeout raises a scheduled delay shorter than 60 seconds to 60 seconds, which in practice affects only the first retry: after jitter, it arrives 48 to 72 seconds later. A `Retry-After` header on a failed response can lengthen the next wait. We accept the header as delay-seconds or an HTTP date. A requested delay longer than the scheduled one replaces it, capped at twice the scheduled delay (after any 60-second raise); a shorter one is ignored, so the header never brings a retry forward. Jitter applies on top. Every retry carries the same `webhook-id`, which is what makes deduplication work. After the final retry the delivery is permanently failed; [replay](#replaying-failed-deliveries) recovers it.

Deliveries are **not ordered**. An `email.delivered` can arrive before the `email.accepted` for the same message, especially when retries are involved. Sort by the `timestamp` field inside the event payload, never by arrival order.

## Operate your endpoints

### Test sends

[`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook) sends a signed synthetic event to your endpoint and returns the outcome synchronously: whether your endpoint accepted it, the HTTP status it returned, and the round-trip latency.

The test body contains the event `type` and `test: true`, signed exactly like a real delivery. For example, an unfiltered probe sends `{"type":"email.delivered","test":true}`. If the endpoint has a filter, the body also includes its equality fields in `data`, such as `{"type":"email_mailbox.message_received","test":true,"data":{"mailbox_id":"MAILBOX_ID"}}`. Use `test: true` to identify synthetic events; these stubs do not mirror a real event payload.

Pass `{"event_type": "email.delivered"}` to pick any type from the catalog, subscribed or not, or omit the body to use the endpoint's first subscribed event type.

Your endpoint has 10 seconds to respond. An unreachable endpoint produces `status: failed` in the response body, while the request itself succeeds. Use this result to debug connectivity. Test sends go straight to your endpoint: they work on a paused endpoint and are not recorded in the delivery attempts log. A `412` means the endpoint cannot be tested yet because it lacks a valid signing secret or subscribed event type. When your workspace presents a [webhook client certificate](/docs/guides/mtls#present-a-client-certificate-on-webhook-deliveries), `client_certificate` reports whether your endpoint accepted it.

For end-to-end testing with real event flows, send to the [sandbox addresses](/docs/guides/email/testing-sandbox): sandbox sends emit real webhook events through the normal delivery path, which is the best way to exercise your handler before going live.

### Replaying failed deliveries

[`POST /v1/webhooks/{webhook_id}/replay`](/docs/api/reference/create-webhook-replay) queues redelivery of deliveries that failed. Events the endpoint already received successfully are skipped, so a replay never double-delivers; a redelivered event carries its original `webhook-id`, so your deduplication check covers replays too. Only failed attempts are replayed: an event your endpoint was never sent has no failed attempt, so a replay does not recover it.

Pass `since`/`until` timestamps to bound the window (default: the last 24 hours to the time of the request). Both bounds are inclusive, and both select on when the delivery was attempted rather than on when the event occurred, so a retry that trailed its event by a day falls in the window by the hour it was attempted. Replay reads the delivery attempts log, which retains three days, so that is the oldest history it reaches: an earlier `since` widens the window without recovering anything older. One replay covers at most the oldest 10,000 events in the window.

The request returns `202` and events are redelivered asynchronously. **A redelivery gets one attempt, not the retry schedule above.** The attempt is recorded and the job is finished whether or not your endpoint accepted it, so a replay into an endpoint that is still broken costs one request per event rather than eight; fix the endpoint and replay again. Those failures leave endpoint health alone: a replay cannot push an endpoint to `degraded` or auto-pause it. A redelivery your endpoint accepts clears both.

Replay a `paused` endpoint and the request still returns `202`, but nothing is redelivered. Re-enable it first, as [Auto-pause and re-enable](#auto-pause-and-re-enable) describes.

Replays are limited to 20 per organization per UTC day; beyond that the request returns a `429` (`WebhookReplayQuotaExceeded`). The response does not include a count or task ID. Track results with [`GET /v1/webhooks/{webhook_id}/attempts`](/docs/api/reference/list-webhook-attempts), which lists recent delivery attempts from newest to oldest with status codes and latency. Each HTTP request has its own entry, so a retried event appears once per attempt, and a redelivery appears as one more.

### Rotating the signing secret

[`POST /v1/webhooks/{webhook_id}/rotate-secret`](/docs/api/reference/rotate-webhook-secret) generates a new secret and returns it once. For the next **24 hours**, Bird signs each delivery with both secrets. The `webhook-signature` header contains the space-delimited signatures (`v1,<old> v1,<new>`), allowing you to deploy the new secret during the overlap. Standard Webhooks libraries try all signatures automatically. After 24 hours the old secret stops signing. An endpoint holds at most 5 concurrently valid secrets, so rotating repeatedly inside the overlap window fails with `WebhookTooManySecrets` until an older secret expires.

### Auto-pause and re-enable

Endpoint `status` is `active`, `degraded`, or `paused`. Recent delivery failures mark an endpoint `degraded` as a health warning; we keep delivering and retrying. An endpoint that fails continuously for about five days is automatically `paused` and all delivery stops; one successful delivery during that period resets the clock. A paused endpoint never resumes on its own. Re-enable it with `PATCH /v1/webhooks/{webhook_id}` and `{"status": "active"}` (or from the [**Webhooks**](/content/dashboard/w/webhooks/index.html) page in the dashboard), then [replay](#replaying-failed-deliveries) to redeliver the attempts that failed before it paused. Re-enable first: a replay requested while the endpoint is still paused redelivers nothing. Events that arrived while it was paused were never sent, so a replay does not recover those.

Any of these returns a `degraded` endpoint to `active`:

| What clears it                             | Why                                                             |
| ------------------------------------------ | --------------------------------------------------------------- |
| A delivery succeeds                        | The endpoint accepted an event again.                           |
| Changing the endpoint's `url`              | The recorded failures describe a destination you no longer use. |
| Re-enabling a `paused` endpoint            | It is re-entering service, so its old failures no longer apply. |
| A [test send](#test-sends) returning `2xx` | You have shown the endpoint is reachable.                       |

Editing an endpoint's description or its subscribed event types says nothing about reachability, so it leaves `degraded` in place, as does a test send that fails.

We email the organization's owners when an endpoint first becomes `degraded`, once per episode rather than once per failed delivery. A later degradation after a recovery emails them again, subject to a 24-hour cooldown: we send at most one degradation email per endpoint every 24 hours, so an endpoint that flaps between `active` and `degraded` does not flood their inbox. Changing the endpoint's `url` resets the cooldown, so the first degradation at a new URL can send an email even within 24 hours of the last one.

## Event catalog

Event payloads contain compact, recipient-scoped facts for correlation with your system. They do not contain the full resource. If you need more context, fetch the resource by its ID. Event types follow `resource.action` naming and are grouped by product; each product's events page carries the per-event payload fields:

- [Email events](/docs/guides/email/events): the delivery lifecycle (`email.accepted` through `email.delivered` or `email.bounced`), engagement (`email.opened`, `email.clicked`), unsubscribes, and [inbound email](/docs/guides/email/receiving-email)
- [SMS events](/docs/guides/sms/events): the message lifecycle from `sms.accepted` to a terminal status
- [WhatsApp webhooks](/docs/guides/whatsapp/webhooks): `whatsapp.accepted` through `whatsapp.delivered`, `whatsapp.read`, `whatsapp.failed`, `whatsapp.rejected`, `whatsapp.received` for an inbound message, `whatsapp.reacted` when a user reacts to one of yours, and `whatsapp.group.join_request_created` and `whatsapp.group.join_request_revoked` when someone asks to join a group that requires approval or withdraws the request
- [Verify events](/docs/guides/verify/events): the verification lifecycle (`verify.verification.created`, `verify.verification.verified`) and each passcode attempt's delivery (`verify.attempt.sent`, `verify.attempt.delivered`, `verify.attempt.undelivered`)
- [Voice events](/docs/guides/voice/events): the call lifecycle (`voice_call.initiated`, `voice_call.answered`, `voice_call.ended`)
- [Realtime webhooks](/docs/guides/realtime/webhooks): channel occupancy (`realtime.channel_occupied`, `realtime.channel_vacated`), presence membership (`realtime.member_added`, `realtime.member_removed`), and client-published events (`realtime.client_event`)
- [Preference events](#preference-events): the cross-channel consent record: `preference.granted`, `preference.revoked`, and `preference.deleted`

Every delivery body is the Standard Webhooks nested envelope with `type`, `timestamp`, and a type-specific `data` object. The `webhook-id` header carries the event identity. The envelope `timestamp` records when the event occurred. The `webhook-timestamp` header records the current delivery attempt and changes on every retry.

```json
{
  "type": "email.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient": "user@example.com",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null,
    "brand_id": null
  }
}
```

Every per-recipient email delivery and engagement event's `data` includes `email_id`, `recipient_id`, `workspace_id`, the `recipient` address, and its envelope `recipient_role`. It also includes the `tags` and `metadata` from the send request, or `null` when not provided. It also carries `broadcast_id`, naming the broadcast the send went out as part of, or `null` when there was no broadcast behind it. On `email.unsubscribed` and `email.list_unsubscribed`, `null` does not rule a broadcast out; [email events](/docs/guides/email/events) covers why. Event types add their own fields to this base. The event schema defines each variant's required and optional fields.

The optional `brand_id` field is in preview. See [email events](/docs/guides/email/events).

Event names are never renamed, and new types are added as products ship, so write your handler to ignore types it doesn't recognize.

### Preference events

Stated preferences (the consent grants and opt-outs described in each channel's guide: [email](/docs/guides/email/unsubscribe-links), [SMS](/docs/guides/sms/opt-outs-and-keywords), [WhatsApp](/docs/guides/whatsapp/opt-outs/preferences)) span channels, so their events name the channel in the payload rather than in the type. `preference.granted` fires when a consent grant takes effect, `preference.revoked` when an opt-out does, and `preference.deleted` when a recorded statement is removed and its key returns to having no record. An event means the key's current record changed: a statement that repeats the current one fires nothing, and one refused as out of order fires nothing either. The envelope `timestamp` is when the statement took effect, which for a backdated statement is when it was made rather than when it reached Bird.

Every payload carries the full preference key: `channel`, `handle`, `sender_scope`, and `topic_id`, with the scoping fields present-with-null when they don't narrow it. Beside the key ride the statement's `coverage`, the `preference_id`, the `transition_id` of the history entry the write appended, and the `contact_id` whose handle matched when the statement was recorded, or null:

```json
{
  "type": "preference.revoked",
  "timestamp": "2026-08-25T14:52:03.192524705Z",
  "data": {
    "preference_id": "prf_01krdgeqcxet5s7t44vh8rt9mg",
    "transition_id": "prt_01krdgeqcxet5s7t44vh8rt9mg",
    "channel": "sms",
    "handle": "+15550001234",
    "sender_scope": null,
    "topic_id": null,
    "coverage": "non_transactional",
    "contact_id": null
  }
}
```

## Next steps

- [Webhooks API reference](/docs/api/reference/create-webhook): full endpoint and schema documentation
- [Email events](/docs/guides/email/events): per-event payload fields
- [Testing & sandbox](/docs/guides/email/testing-sandbox): sandbox sends drive real webhook deliveries, ideal for testing handlers
