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
destinationHow each delivery to the endpoint is built.
Untergeordnete Attribute anzeigen
Posts the signed event to the endpoint's url unchanged.
destination.typeValue: webhook
Sends the request a connector action builds, with the credentials stored for this endpoint. The endpoint's URL comes from its connector setup, so updating the endpoint with a url returns a 422.
destination.typeValue: connector
destination.connectorUntergeordnete Attribute anzeigen
destination.connector.connector_idStable identifier of a connector, such as claude_managed_agents.
destination.connector.actionAction of the connector that each delivery runs.
destination.connector.connection_nameLabel of the credentials the endpoint delivers with.
destination.connector.configThe connector's nonsecret fields as the endpoint delivers with them. Secret fields are never returned.
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.
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.