Documentation
Sign inGet started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Create a webhook endpoint

POST
/v1/webhooks
bird webhooks create https://example.com/webhooks/bird \
  --description 'Production delivery + bounce notifications' \
  --events email.delivered \
  --events email.bounced
Response201
{
  "id": "whk_01krdgeqcxet5s7t44vh8rt9mg",
  "url": "https://example.com/webhook",
  "description": "Production webhook endpoint",
  "events": [
    "email.delivered",
    "email.bounced"
  ],
  "status": "active",
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z",
  "secret": "whsec_base64encodedvalue"
}
Registers an active webhook endpoint that receives the event types in events as signed HTTPS POST requests. See the webhooks guide for delivery, signing, and retry behavior.
The 201 response is the only response that includes the signing secret (whsec_ prefix). Store it immediately; if it is lost, rotate the signing secret.
A non-HTTPS or non-public url, an unknown event type, or exceeding the organization's endpoint limit returns 422.
Request Payload
url
string
required
HTTPS URL to deliver events to, at most 2048 characters. The host must be publicly reachable: URLs on private, loopback, or link-local addresses are rejected with a 422.
events
array of string
required
Event types to subscribe to; the endpoint receives only matching events. Types outside the event catalog return a 422, and an endpoint holds at most 100 entries.
description
string
Human-readable label for this endpoint, up to 256 characters.
Response Payload
id
string
required
Unique identifier for the endpoint (whk_ prefix). Accepted as webhook_id by every /v1/webhooks/{webhook_id} operation.
url
string
required
HTTPS URL where the API delivers events for this endpoint.
description
string
Human-readable label for the endpoint.
events
array of string
required
Event types this endpoint is subscribed to; only matching events are delivered. Change the set with Update a webhook endpoint.
status
string
required
Delivery state of the endpoint.
  • active: The initial state; events are being delivered normally.
  • degraded: Recent deliveries are failing. We keep delivering and retrying, and the endpoint returns to active automatically once deliveries succeed again.
  • paused: All delivery is stopped, either because an update set status to paused or automatically after sustained delivery failures. A paused endpoint never resumes on its own: re-enable it with Update a webhook endpoint, then recover the missed events with Replay missed events.
Possible values: active, degraded, paused
created_at
string
required
updated_at
string
required
secret
string
required
Signing secret for this endpoint (whsec_ prefix), used to verify every delivery signature. Present in this response only: store it immediately, it cannot be retrieved again. If you lose it, mint a new one with Rotate webhook signing secret.