# `bird webhooks create`

## Usage

```bash
bird webhooks create <url> [flags]
```

## Description

Create a webhook endpoint

Registers a webhook endpoint that receives this workspace's events as signed HTTPS
`POST` requests. The endpoint starts `active` and receives only the event types listed
in `events`. Delivery, signing, and retry behavior are covered in the
[webhooks guide](/docs/guides/webhooks).

The `201` response is the only place the endpoint's signing secret (`whsec_` prefix)
ever appears: store it immediately. If you lose it, mint a new one with
[Rotate webhook signing secret](/docs/api/reference/rotate-webhook-secret). After
creating, [Send a test event](/docs/api/reference/test-webhook) to confirm your
receiver is reachable and verifies signatures correctly.

Invalid input (a non-HTTPS or non-public `url`, an event type outside the catalog)
returns a `422`, as does exceeding your organization's webhook endpoint limit
(`WebhookTooManyEndpoints`).

Build the request from the &lt;url> argument and flags, a JSON WebhookEndpointCreate body via
--body-file ("-" reads stdin), or both — an inline value 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 create --example

# the body it prints:
```

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

## Options

#### Endpoint

| Name                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--events <v1,v2,…>` | Event types to subscribe to; the endpoint receives only matching events. Types outside the event catalog return a 422, and an endpoint holds at most 100 entries. Platform types may be combined with realtime.\* types on one endpoint, all signed with the endpoint's single secret. Server-enforced (returns 422 otherwise): a realtime.\* type requires the realtime object, and realtime requires at least one realtime.\* type. |
| `--description`      | Human-readable label for this endpoint, up to 256 characters.                                                                                                                                                                                                                                                                                                                                                                         |

#### 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 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 rotate-secret`](/docs/cli/reference/webhooks-rotate-secret) | Rotate webhook signing secret |
| [`bird webhooks test`](/docs/cli/reference/webhooks-test)                   | Send a test event             |