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 body file or stdin and are never echoed back; the signing secret is shown once, at creation.

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 and fields in webhooks create --help or the tool's connector_id description: 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 or its nonsecret fields. 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, give its 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 --secret-env name=ENV_VAR or --secret-stdin name for each secret one, never a secret value as a flag; the MCP tool takes connector_id, config and credentials. The response shows the signing secret once; hand it to the user to store, 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. The call succeeds either way, so read the result's status: only when the receiver accepted the event is the setup done. When it failed, report its HTTP status and response body, or for an unreachable receiver its error, to the user, fix the cause as below, and test again before saying it works. Once the test was accepted, ask the user to confirm the event shows up on their side. Next: bird webhooks attempts or bird webhooks update or bird webhooks delete

Commands