Update a webhook endpoint

PATCH

/v1/webhooks/{webhook_id}

const endpoint = await bird.webhooks.update("whk_01krdgeqcxet5s7t44vh8rt9mg", {
  events: ["email.delivered"],
});
console.log(endpoint.events);

endpoint = client.webhooks.update(
    "whk_01krdgeqcxet5s7t44vh8rt9mg",
    events=["email.delivered"],
)
print(endpoint.events)

endpoint, err := client.Webhooks.Update(context.Background(), "whk_123", bird.WebhooksUpdateParams{
	Events: []bird.WebhookEventType{"email.delivered"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(endpoint.Events)

$endpoint = $bird->webhooks->update(
    'whk_01krdgeqcxet5s7t44vh8rt9mg',
    (new WebhookEndpointUpdate())->setEvents(['email.delivered']),
);
echo implode(',', $endpoint->getEvents() ?? []);

bird webhooks update <webhook-id> \
  --description 'Updated webhook endpoint' \
  --events email.delivered \
  --events email.bounced \
  --events email.complained \
  --status active \
  --url https://example.com/webhook

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"
  }'

Reactie200

{
  "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.

Verzoekpayload

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

string

verplicht

Unique identifier for the endpoint (whk_ prefix). Accepted as webhook_id by every /v1/webhooks/{webhook_id} operation.

url

string

verplicht

HTTPS URL where the API delivers events for this endpoint.

description

string

Human-readable label for the endpoint.

events

array of string

verplicht

Event types this endpoint is subscribed to; only matching events are delivered. Change the set with Update a webhook endpoint.

status

string

verplicht

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

verplicht

updated_at

string

verplicht

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideWebhooks done right: reliable delivery events Understand the conceptHow do I verify a webhook signature?Follow the learning pathOperate messaging reliably Implementation guideWebhooks & events

Try the practice and get an implementation brief

const endpoint = await bird.webhooks.update("whk_01krdgeqcxet5s7t44vh8rt9mg", {
  events: ["email.delivered"],
});
console.log(endpoint.events);

endpoint = client.webhooks.update(
    "whk_01krdgeqcxet5s7t44vh8rt9mg",
    events=["email.delivered"],
)
print(endpoint.events)

endpoint, err := client.Webhooks.Update(context.Background(), "whk_123", bird.WebhooksUpdateParams{
	Events: []bird.WebhookEventType{"email.delivered"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(endpoint.Events)

$endpoint = $bird->webhooks->update(
    'whk_01krdgeqcxet5s7t44vh8rt9mg',
    (new WebhookEndpointUpdate())->setEvents(['email.delivered']),
);
echo implode(',', $endpoint->getEvents() ?? []);

bird webhooks update <webhook-id> \
  --description 'Updated webhook endpoint' \
  --events email.delivered \
  --events email.bounced \
  --events email.complained \
  --status active \
  --url https://example.com/webhook

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"
  }'

Reactie200

{
  "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"
}