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

Update a webhook endpoint

PATCH
/v1/webhooks/{webhook_id}
curl -X PATCH "https://us1.platform.bird.com/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "description": "Updated webhook endpoint",
    "events": [
      "email.delivered",
      "email.bounced",
      "email.complained"
    ],
    "status": "active"
  }'
Response200
{
  "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"
}
Updates the webhook endpoint. Only the fields you send change: events replaces the whole subscription set, and status pauses or re-enables delivery.
The 200 response is the updated endpoint. Invalid input (a non-HTTPS or non-public url, an event type outside the catalog) returns a 422.
Parameters
webhook_id
string
ID of the webhook endpoint (whk_ prefix), as returned when it was created.
Request Payload
url
string
Replacement delivery URL. Same rules as at creation: HTTPS, at most 2048 characters, and the host must be publicly reachable (private, loopback, and link-local addresses return a 422). Omit to keep the current URL.
description
string
Human-readable label for this endpoint, up to 256 characters.
events
array of string
Replaces all event subscriptions with this list. Omit to keep the current set. Types outside the event catalog return a 422.
status
string
paused stops all deliveries; active re-enables a paused endpoint. Omit to leave the status unchanged. Events that fire while paused are not delivered; after re-enabling, recover them with Replay missed events. A degraded endpoint cannot be reset through this field: it returns to active automatically once deliveries succeed again.
Possible values: active, paused
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