bird webhooks

Usage

bird webhooks

Description

An endpoint subscribes to event types and receives signed deliveries. Its signing secret can be rotated, and delivery attempts are recorded per endpoint so a failure can be inspected after the fact.

Reads return JSON; list is paginated. Mutations take flags and/or a --body-file JSON body (flags overriding); run --example to print the body shape or --dry-run to preview the request. Destructive commands require --yes.

Procedure

Send events to a webhook destination, and prove one arrives

Point Bird's events at a destination the user owns: an HTTPS endpoint such as a Zapier, Make or n8n catch hook, or a connector such as Claude Managed Agents or Grok Bot, then send a test event and confirm it arrived. Re-running the setup for a plain endpoint reuses it instead of creating a second one. Secrets go in through a file or stdin and are never echoed back; the CLI writes the signing secret to a file, and the MCP tools return it only with reveal_secret.

Requires: The user owns the receiving side, so you cannot create it for them. For a plain endpoint, ask for its HTTPS URL, such as a Zapier "Catch Hook", a Make custom webhook or an n8n Webhook node's production URL. For a connector, read its setup steps at https://bird.com/docs/ai/webhook-connectors and its fields from its setup schema: --request-schema with --connector in the CLI, or webhooks_create with connector_id alone over MCP. A create missing a field names the connector's fields. Walk the user through the steps, collect the values they produce, then create the webhook and send a test event. Ask which events to send.

1. bird webhooks list — For a plain endpoint, filter by the receiver's url to look for one this setup made before. Several endpoints can share a URL, so a match is this setup's only if its description and events say so; ask the user when they don't. Reuse that match, without a connector destination, changing it with webhooks.update. For a connector, create a new endpoint: Bird builds its URL from the fields, two endpoints of one connector can reach different accounts, and an update cannot change the connector itself. The filter finds matches, it does not stop duplicates. Next: bird webhooks create or bird webhooks update or bird webhooks test
2. bird webhooks create — For a connector on the CLI, prefer bird webhooks connect <connector>, which creates and reports in one step and names the test under next; MCP has no connect tool, and its create does the same. Otherwise, give the connector's id, nonsecret fields and secret fields, and omit url: Bird builds it. On the CLI, pass --connector and a --field name=value for each nonsecret field and --credential name=FILE (or name=- for stdin) for each secret one, never a secret value as a flag; the MCP tool takes connector_id, config and credentials. The CLI writes the signing secret to a file only the user can read and prints its path; the MCP tool withholds it unless reveal_secret is set. A connector never needs it, and never repeat credentials back. Next: bird webhooks test
3. bird webhooks test — Sends one synthetic event and reports whether the receiver accepted it, its HTTP status and the time it took. A connector whose platform can be read without starting anything, such as Claude Managed Agents, is read instead, which checks its fields; saving a connector endpoint never contacts its platform, so this is the check. The call succeeds either way, so read the result's status and kind: only when it is delivered is the setup done. When it failed, report its HTTP status and response body, or for an unreachable receiver its error, to the user. When a connector's platform answer identifies a wrong field, field names it. Fix the cause as below, and test again before saying it works. Once a delivery test was accepted, ask the user to confirm the event shows up on their side. A probe test sends no event, so tell the user the fields check out and that the first real message is the end-to-end confirmation. Next: bird webhooks attempts or bird webhooks update or bird webhooks delete

Commands