Create a webhook endpoint
/v1/webhooksconst created = await bird.webhooks.create({
url: "https://acme.com/hooks/bird",
events: ["email.delivered", "email.bounced"],
description: "Delivery pipeline",
});
console.log(created.id, created.secret);created = client.webhooks.create(
url="https://acme.com/hooks/bird",
events=["email.delivered", "email.bounced"],
description="Delivery pipeline",
)
print(created.id, created.secret)created, err := client.Webhooks.Create(context.Background(), bird.WebhooksCreateParams{
URL: "https://acme.com/hooks/bird",
Events: []bird.WebhookEventType{"email.delivered", "email.bounced"},
Description: bird.Ptr("Delivery pipeline"),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(created.Id, created.Secret)$created = $bird->webhooks->create(
(new WebhookEndpointCreate())
->setUrl('https://acme.com/hooks/bird')
->setEvents(['email.delivered', 'email.bounced'])
->setDescription('Delivery pipeline'),
);
echo $created->getId(), ' ', $created->getSecret();bird webhooks create https://example.com/webhooks/bird \
--description 'Production delivery + bounce notifications' \
--events email.delivered \
--events email.bouncedcurl -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"
}'{
"id": "whk_01krdgeqcxet5s7t44vh8rt9mg",
"url": "https://example.com/webhook",
"description": "Production webhook endpoint",
"filter": null,
"events": [
"email.delivered",
"email.bounced"
],
"status": "active",
"destination": {
"type": "webhook"
},
"created_at": "2026-05-20T09:14:52Z",
"updated_at": "2026-05-25T16:42:01Z",
"secret": "whsec_base64encodedvalue",
"next": [
{
"kind": "operation"
}
]
}
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.
Anfrage-Nutzlast
urlHTTPS 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. Required unless destination is a connector, whose URL comes from the connector and its config; a URL given with one must equal it.
filterLimit delivery to one mailbox and only email_mailbox events. Omit to include all resources.
eventsEvent 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.
descriptionHuman-readable label for this endpoint, up to 256 characters.
destinationHow each delivery is built. Omit to post the signed event to url unchanged, the same as {"type": "webhook"}.
Antwort-Payload
idUnique identifier for the endpoint (whk_ prefix). Accepted as webhook_id by every /v1/webhooks/{webhook_id} operation.
urlHTTPS URL where the API delivers events for this endpoint.
descriptionHuman-readable label for the endpoint.
filterMailbox scope configured through filter, or null.
eventsEvent types this endpoint is subscribed to; only matching events are delivered. Change the set with Update a webhook endpoint.
statusDelivery 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 toactiveautomatically once deliveries succeed again.paused: All delivery is stopped, either because an update setstatustopausedor 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
created_atupdated_atsecretSigning 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.
nextWhat to do next with this endpoint. Empty: deliveries start as the events happen, with nothing left to set up.
Untergeordnete Attribute anzeigen
next.kindWhat you do about this step.
operation: call the operation named inoperation, 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.descriptionA short, human-readable label for the step, suitable for display.
next.operationThe 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.paramsThe 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.urlA 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.
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.