`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 required fields are checked before anything is sent. The response is the only place the signing secret appears, and it can never be read back afterward, only rotated.

Connectors (--connector), each delivering a request its platform needs instead of the raw event. Omit the URL: Bird builds it. claude_managed_agents Claude Managed Agents. Send each message you receive to your Claude managed agent. agent_id (--field agent_id=..., required): Returned when you create the agent. Sessions use its latest version. environment_id (--field environment_id=..., required): Returned when you create the environment. api_key (secret: --secret-env api_key=ENV_VAR or --secret-stdin api_key, required): From the Claude workspace your agent runs in. events: whatsapp.received, sms.received, email_mailbox.message_received, amb.received setup 1, on the platform: 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, on the platform: Create an API key. In the Claude workspace your agent runs in. See https://platform.claude.com/settings/keys setup 3, on the platform: 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 (--field webhook_url=..., required): The routine's webhook URL. sender_key (secret: --secret-env sender_key=ENV_VAR or --secret-stdin sender_key, 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, on the platform: 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

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, listed below, instead of posting the raw event to the URL.
`--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