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

Réponse200

{
  "id": "whk_01krdgeqcxet5s7t44vh8rt9mg",
  "url": "https://example.com/webhook",
  "description": "Production webhook endpoint",
  "filter": null,
  "events": [
    "email.delivered",
    "email.bounced"
  ],
  "status": "active",
  "destination": {
    "type": "webhook"
  },
  "next": [
    {
      "kind": "operation"
    }
  ],
  "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. Updating a connector endpoint does not contact its platform. next suggests testing the endpoint, which checks its fields with the platform.

Paramètres

webhook_idstring

ID of the webhook endpoint (whk_ prefix), as returned when it was created.

Corps de la requête

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. A connector endpoint's URL comes from its connector and cannot be replaced: any value returns a 422.

description

string

Human-readable label for this endpoint, up to 256 characters.

filter

nullable object

Replace the mailbox scope. Omit to keep it, or send null to include all resources. Scoped endpoints accept only email_mailbox events.

Afficher les paramètres enfants

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.

destination

object

Changes to how deliveries are built, shaped as at creation. Only a connector destination takes connector; on any other endpoint it returns a 422. Omit to keep the destination.

Afficher les paramètres enfants

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 and a replay cannot recover them, because they were never attempted; after re-enabling, Replay failed deliveries reaches only the deliveries that failed before the pause. A degraded endpoint cannot be reset through this field: it returns to active automatically once deliveries succeed again.

Possible values: active, paused

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 where the API delivers events for this endpoint.

description

string

Human-readable label for the endpoint.

filter

nullable object

obligatoire

Mailbox scope configured through filter, or null.

Afficher les attributs enfants

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. 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 Replay failed deliveries to recover the deliveries that failed before the pause. Events that arrived while it was paused were never attempted, so a replay does not reach them.

Possible values: active, degraded, paused

destination

object

How each delivery to the endpoint is built.

Afficher les attributs enfants

next

array of object

What to do next with this endpoint. The responses that create or update a connector endpoint suggest testing it, which checks its fields with the connected platform. Other responses that return one endpoint return an empty list, and lists omit it.

Afficher les attributs enfants

next.kind

string

obligatoire

What you do about this step.

operation: call the operation named in operation, then read again.
external: act somewhere this API does not reach, then read again.
wait: nothing is asked of you, so read again later.
terminal: nothing you do resolves this, so stop retrying.

Tolerate a value you do not recognize: show the description and offer no action.

Possible values (may grow over time): operation, external, wait, terminal

next.description

string

obligatoire

A short, human-readable label for the step, suitable for display.

next.operation

string

The operationId to call. Present only when kind is operation. The operation's own schema says how to call it; this says only which one, and what to address it with.

next.params

object

The parameters that address the operation, by name: {"sender_id": "…"} for an operation on /v1/sms/senders/{sender_id}/requirements. A parameter the operation takes in its query string is given the same way, so an operation addressed as ?subject_id= carries {"subject_id": "…"}. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when kind is operation and the operation names a subject. A request body, when the operation takes one, is described by the operation's own schema and never appears here.

next.url

string

A URL to open. Present only when kind is external, and only when the step has one. An external step whose description says to go and do something with no URL to open is normal.

created_at

string

obligatoire

updated_at

string

obligatoire

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Essayez la pratique et obtenez un guide d'implémentation

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

Réponse200

{
  "id": "whk_01krdgeqcxet5s7t44vh8rt9mg",
  "url": "https://example.com/webhook",
  "description": "Production webhook endpoint",
  "filter": null,
  "events": [
    "email.delivered",
    "email.bounced"
  ],
  "status": "active",
  "destination": {
    "type": "webhook"
  },
  "next": [
    {
      "kind": "operation"
    }
  ],
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z"
}

Update a webhook endpoint

Paramètres

Corps de la requête

Contenu de la réponse

Ressources associées