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"}.
Untergeordnete Parameter anzeigen
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.connectorThe connector to deliver through and the values it needs. Omit the endpoint's url: Bird builds it from the connector's URL and these config values, and a URL given anyway must equal that. The credentials belong to this endpoint alone, and deleting the endpoint erases them.
Untergeordnete Parameter anzeigen
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.vault_id(config, optional): A credential vault the agent uses, such as the one holding its Bird MCP credential, so it can reply through Bird.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.
- Setup 4: Optionally, add a credential vault. To let the agent reply through Bird, store its Bird MCP credential in a Claude credential vault and give the vault ID here. Each session gets that vault. See https://platform.claude.com/docs/en/managed-agents/vaults.
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.
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.
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.