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"
}
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.
Request Payload
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.
Show child parameters
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"}.
Show child parameters
Posts the signed event to the endpoint's url unchanged.
destination.typeValue: webhook
Sends the request a connector action builds, with credentials stored for this endpoint.
destination.typeValue: connector
destination.connectorShow child parameters
destination.connector.connector_idThe connector to deliver through. Each connector, its fields and the setup to do on its platform first:
claude_managed_agents: Claude Managed Agents. Send each message you receive to your Claude managed agent.agent_id(config, required): Returned when you create the agent. Sessions use its latest version.environment_id(config, required): Returned when you create the environment.api_key(secret, incredentials, required): From the Claude workspace your agent runs in.- Events:
whatsapp.received,sms.received,email_mailbox.message_received,amb.received. - Setup 1: First, set up your agent in Claude. In the Claude Console, create the agent, its environment and an API key in the same workspace, then come back here with their IDs and the key. See https://platform.claude.com/docs/en/managed-agents/quickstart#create-your-first-session.
- Setup 2: Create an API key. In the Claude workspace your agent runs in. See https://platform.claude.com/settings/keys.
- Setup 3: Copy the agent and environment IDs. Each create returns its ID. See https://platform.claude.com/docs/en/managed-agents/quickstart#create-your-first-session.
grok_bot: Grok Bot. Send each message you receive to a Grok Bot routine.webhook_url(config, required): The routine's webhook URL.sender_key(secret, incredentials, required): The routine's sender key. Bird sends it only as the Bearer token.- Events:
whatsapp.received,sms.received,email_mailbox.message_received,amb.received. - Setup 1: First, ask Grok Bot to create a routine. Ask Grok Bot to create a routine with a webhook trigger, then paste the webhook URL and sender key it gives you below. See https://cursor.com/docs/cloud-agent/automations#webhook-triggers.
destination.connector.actionAction of the connector that each delivery runs. Omit when the connector has one action. An action the connector does not have, or events the action does not accept, returns a 422.
destination.connector.credentialsValues for the connector's secret fields, keyed by field name. Every required secret field must be present, after merging with the stored values on an update, and a key the connector does not declare as secret returns a 422. No response includes these values.
destination.connector.configValues for the connector's nonsecret fields, keyed by field name, such as the URL the endpoint's requests go to. A URL must be HTTPS, on one of the connector's allowed_origins, and under its path_prefix when it has one. It cannot include user info, a fragment, an IP address as its host, dot segments, or encoded slashes.
Response 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.
Show child attributes
filter.mailbox_idMailbox to receive events for. Must belong to this workspace; a mailbox outside it returns 422.
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.
Show child attributes
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.connectorShow child attributes
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.
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.
Related resources
Continue with the documentation, guides and examples for this topic.