# `bird webhooks test`

## Usage

```bash
bird webhooks test <webhook-id> [flags]
```

## Description

Send a test event

Sends a signed synthetic event to the endpoint's URL and returns the outcome
synchronously: whether your endpoint accepted it, the HTTP status it returned, and the
round-trip latency. Use it to verify your receiver is reachable and its signature
verification is correct. An unreachable endpoint is reported in the response body as
`status: failed`, not as a request error. Your endpoint has 10 seconds to respond.

The test body is a minimal JSON stub carrying only the event `type` (it does not
mirror a real event payload), signed exactly like a real delivery. Test sends go
straight to your endpoint: they work on a paused endpoint and are not recorded in
[List delivery attempts](/docs/api/reference/list-webhook-attempts).

A `412` means the endpoint cannot be tested yet: it has no valid signing secret, or no
subscribed event types to fall back on when `event_type` is omitted.

Build the request from flags, a JSON WebhookTestRequest 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 test --example

# the body it prints:
```

```json
{
  "event_type": "email.delivered"
}
```

## Options

#### Event

| Name           | Description                                                                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--event-type` | Event type to simulate. Any type from the event catalog is accepted, whether or not the endpoint subscribes to it; an unknown type returns a 422. When omitted, the endpoint's first subscribed event type is used. |

#### 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 rotate-secret`](/docs/cli/reference/webhooks-rotate-secret) | Rotate webhook signing secret |