`bird webhooks create`

Usage

Code example

bird webhooks create [url] [flags]

Register an endpoint to receive this workspace's events, active immediately. Your own endpoint needs a URL and events. A connector endpoint needs neither: Bird builds its URL, and events defaults to every event the connector accepts. Its setup is checked against the schema the connector publishes, which --schema prints, before anything is sent. The response is the only place the signing secret appears, and it can never be read back afterward, only rotated. https://bird.com/docs/ai/webhook-connectors lists the connectors with their fields, accepted events and platform setup.

Build the request from flags, a JSON WebhookEndpointCreate body via --body-file ("-" reads stdin), or both — a flag overrides the matching body field. Run --example to print a ready-to-edit body, or --dry-run to print the resolved request without sending it.

Procedure

Step 2 of 3 of "Send events to a webhook destination, and prove one arrives". Previous: bird webhooks list. Next: bird webhooks test.

Examples

Code example

# print the body shape (no credentials needed)
bird webhooks create --example

# the body it prints:

Code example

{
  "description": "Production delivery + bounce notifications",
  "events": ["email.delivered", "email.bounced"],
  "url": "https://example.com/webhooks/bird"
}

Code example

# deliver to your own endpoint
bird webhooks create https://example.com/bird --events sms.received,whatsapp.received

# start a Claude managed agent session for each inbound message
bird webhooks create --connector claude_managed_agents --field agent_id=agent_123 --field environment_id=env_123 --secret-env api_key=ANTHROPIC_API_KEY

Options

Endpoint

Name	Description
`--url`	HTTPS URL to deliver events to, also accepted as the positional argument. Omit it with --connector: Bird builds the URL.
`--events <v1,v2,…>`	Event types to subscribe to; the endpoint receives only matching events. See https://bird.com/docs/guides/webhooks#event-catalog for the current values.
`--description`	Human-readable label for this endpoint, up to 256 characters.

Connector

Name	Description
`--connector`	Deliver through this connector instead of posting the raw event to the URL. https://bird.com/docs/ai/webhook-connectors lists them.
`--action`	The connector action each delivery runs. Omit it for a connector with one action; https://bird.com/docs/ai/webhook-connectors lists the actions of the others.
`--schema`	Print the --connector's setup schema, its fields and actions, instead of creating an endpoint.
`--field <key=value>`	A nonsecret field of the connector, as name=value; repeat for each. Secret fields take --secret-env or --secret-stdin, never a value on the command line.
`--secret-env <key=value>`	A secret field of the connector, read from an environment variable, as name=ENV_VAR; repeat for each. Only the variable's name is on the command line.
`--secret-stdin`	A secret field of the connector, read from stdin. Takes one field, and cannot share stdin with --body-file -.

Request

Name	Description
`--body-file`	Read the JSON request body from this file; "-" reads stdin
`--example`	Print a complete example request body, then exit
`--dry-run`	Print the resolved request without sending it, then exit
`--idempotency-key`	Deduplication key; a retry with the same key won't act twice

Options

Name	Description
`--response-schema`	Print the fields this command returns, then exit

Name	Description
`bird webhooks attempts`	List delivery attempts
`bird webhooks delete`	Delete a webhook endpoint
`bird webhooks get`	Get a webhook endpoint
`bird webhooks list`	List webhook endpoints
`bird webhooks replay`	Replay failed deliveries
`bird webhooks rotate-secret`	Rotate webhook signing secret
`bird webhooks test`	Test a webhook with a sample event
`bird webhooks update`	Update a webhook endpoint

Continue with the documentation, guides and examples for this topic.

Try the practice and get an implementation brief

Related resources