---
title: "bird webhooks connect"
description: "Connect a connector to this workspace's events"
canonical: "https://bird.com/docs/cli/reference/webhooks-connect"
---

# `bird webhooks connect`

## Usage

```bash
bird webhooks connect <connector> [flags]
```

## Description

Connect a connector to this workspace's events

Create a connector endpoint in one step: the connector's required fields come from its published setup schema, and a missing one is named with the flag that sets it. Saving does not contact the platform. The summary gives the webhook ID, events and filter, and no secret, and names `bird webhooks test` under `next`, which checks the fields with the platform; fix a value it names with bird webhooks update. https://bird.com/docs/ai/webhook-connectors lists the connectors with their fields 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.

## Examples

```bash
# print the body shape (no credentials needed)
bird webhooks connect --example

# the body it prints:
```

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

```bash
# send one mailbox's email to a Grok Bot routine
bird webhooks connect grok_bot --mailbox YOUR_MAILBOX_ADDRESS --field webhook_url=YOUR_ROUTINE_WEBHOOK_URL --credential sender_key=- < grok-key.txt
```

## Options

#### Connector

| Name                       | Description                                                                                                                                                                                                                                                    |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--mailbox`                | Deliver only this mailbox's events, by ID or address; an address is looked up, which needs the mailbox:read scope. --events then defaults to the mailbox events the connector accepts.                                                                         |
| `--events <v1,v2,…>`       | Event types to deliver. Defaults to the events the connector's action lists, narrowed to its mailbox events with --mailbox. An action that accepts every event needs them named, except with --mailbox, where it defaults to email\_mailbox.message\_received. |
| `--description`            | Human-readable label for this endpoint, up to 256 characters.                                                                                                                                                                                                  |
| `--action`                 | The connector action each delivery runs. Omit it for a connector with one action.                                                                                                                                                                              |
| `--field <key=value>`      | A nonsecret field of the connector, as name=value; repeat for each. Secret fields take --credential, never a value on the command line.                                                                                                                        |
| `--credential <key=value>` | A secret field of the connector, as name=FILE: the file holding its value, or - for stdin. Repeat for each; only one can read stdin. The value never goes on the command line.                                                                                 |

#### 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 |

## Related

| Name                                                                        | Description                        |
| --------------------------------------------------------------------------- | ---------------------------------- |
| [`bird webhooks attempts`](/docs/cli/reference/webhooks-attempts)           | List delivery attempts             |
| [`bird webhooks create`](/docs/cli/reference/webhooks-create)               | Create a webhook endpoint          |
| [`bird webhooks delete`](/docs/cli/reference/webhooks-delete)               | Delete a webhook endpoint          |
| [`bird webhooks get`](/docs/cli/reference/webhooks-get)                     | Get a webhook endpoint             |
| [`bird webhooks list`](/docs/cli/reference/webhooks-list)                   | List webhook endpoints             |
| [`bird webhooks replay`](/docs/cli/reference/webhooks-replay)               | Replay failed deliveries           |
| [`bird webhooks rotate-secret`](/docs/cli/reference/webhooks-rotate-secret) | Rotate webhook signing secret      |
| [`bird webhooks test`](/docs/cli/reference/webhooks-test)                   | Test a webhook with a sample event |
| [`bird webhooks update`](/docs/cli/reference/webhooks-update)               | Update a webhook endpoint          |

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)