Documentation
Sign inGet started
Commencer
Guides
Référence API
SDK et CLI
Base de connaissances
Changelog

Create a webhook endpoint

POST
/v1/webhooks
curl -X POST "https://us1.platform.bird.com/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/bird",
    "events": [
      "email.delivered",
      "email.bounced"
    ],
    "description": "Production delivery + bounce notifications"
  }'
Registers a webhook endpoint that receives this workspace's events as signed HTTPS POST requests. The endpoint starts active and receives only the event types listed in events. Delivery, signing, and retry behavior are covered in the webhooks guide.
The 201 response is the only place the endpoint's signing secret (whsec_ prefix) ever appears: store it immediately. If you lose it, mint a new one with Rotate webhook signing secret. After creating, Send a test event to confirm your receiver is reachable and verifies signatures correctly.
Invalid input (a non-HTTPS or non-public url, an event type outside the catalog) returns a 422, as does exceeding your organization's webhook endpoint limit (WebhookTooManyEndpoints).
Corps de la requête
url
string
obligatoire
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
obligatoire
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. Platform types may be combined with realtime.* types on one endpoint, all signed with the endpoint's single secret. Server-enforced (returns 422 otherwise): a realtime.* type requires the realtime object, and realtime requires at least one realtime.* type.
description
string
Human-readable label for this endpoint, up to 256 characters.
Contenu de la réponse
id
string
obligatoire
Unique identifier for the endpoint (whk_ prefix). Accepted as webhook_id by every /v1/webhooks/{webhook_id} operation.
url
string
obligatoire
HTTPS URL Bird delivers this endpoint's events to.
description
string
Human-readable label for the endpoint.
events
array of string
obligatoire
Event types this endpoint is subscribed to; only matching events are delivered. Change the set with Update a webhook endpoint.
status
string
obligatoire
Delivery state of the endpoint.
  • active: the initial state; events are being delivered normally.
  • degraded: recent deliveries are failing. Bird keeps 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
obligatoire
updated_at
string
obligatoire
secret
string
obligatoire
Signing secret for this endpoint (whsec_ prefix), used to verify the webhook-signature header on every delivery. 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.