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.
Corps de la requête
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.
Afficher les paramètres enfants
filter.mailbox_idMailbox to receive events for. Must belong to this workspace; a mailbox outside it returns 422.
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"}.
Contenu de la réponse
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.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.