> ## Documentation Index
> Fetch the complete documentation index at: https://jetemail.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# webhooks

> Create, list, query, and replay webhook subscriptions.

`jetemail webhooks` covers everything under `/webhooks`. Authentication uses your `api_…` key.

```
webhooks
├── list | get <uuid> | create | update | delete <uuid>
├── query              POST /webhooks/query
└── replay             POST /webhooks/replay
```

## `list` / `get`

```sh theme={null}
jetemail webhooks list
jetemail webhooks get <uuid>
```

## `create`

```sh theme={null}
jetemail webhooks create \
  --name "prod" \
  --url https://api.example.com/hook \
  --event outbound.delivered \
  --event outbound.bounced \
  --status 1
```

| Flag                          | Description                                                                             |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| `--name <str>`                | Display name.                                                                           |
| `--url <url>`                 | Endpoint to POST events to.                                                             |
| `--event <type>`              | Event type to subscribe to (e.g. `outbound.delivered`, `inbound.received`). Repeatable. |
| `--status <0\|1>`             | `0` disabled, `1` enabled.                                                              |
| `--filter-user <user>`        | Restrict to a specific SMTP user. Repeatable.                                           |
| `--filter-domain <domain>`    | Restrict to a specific domain. Repeatable.                                              |
| `--body-json` / `--field k=v` | See [Body escape hatches](/cli/body-json).                                              |

See [Webhook events](/webhooks/events) for the complete event-type list.

## `update`

```sh theme={null}
jetemail webhooks update \
  --uuid <uuid> \
  --status 0
```

Same flags as `create`, plus `--uuid <uuid>` to select the webhook.

## `delete`

```sh theme={null}
jetemail webhooks delete <uuid>
```

## `query`

Search the webhook event history. Mirrors `POST /webhooks/query`.

```sh theme={null}
jetemail webhooks query \
  --event-type outbound.bounced \
  --date-from 1715126400 \
  --limit 100
```

| Flag                           | Description                       |
| ------------------------------ | --------------------------------- |
| `--uuid <uuid>`                | Restrict to one webhook.          |
| `--event-id <id>`              | Single event.                     |
| `--event-type <type>`          | Filter by type.                   |
| `--source-uid <uid>`           | Filter by underlying message UID. |
| `--status <state>`             | `delivered`, `failed`, `pending`. |
| `--date-from <epoch>`          | Lower bound (Unix seconds).       |
| `--date-to <epoch>`            | Upper bound.                      |
| `--limit <n>` / `--offset <n>` | Pagination.                       |
| `--body-json <src>`            | Raw body override.                |

## `replay`

Re-fire a past event to its webhook endpoint(s).

```sh theme={null}
jetemail webhooks replay --event-id <event-id>
jetemail webhooks replay --source-uid <message-uid>
jetemail webhooks replay --uuid <webhook-uuid>      # replay every event for one subscription
```

| Flag                 | Description                                 |
| -------------------- | ------------------------------------------- |
| `--event-id <id>`    | Replay one specific event.                  |
| `--source-uid <uid>` | Replay every event tied to a message UID.   |
| `--uuid <webhook>`   | Replay events for one webhook subscription. |
| `--body-json <src>`  | Raw body override.                          |

## Local development

To test a handler on your dev machine, expose it on a public URL with [ngrok](https://ngrok.com) (or any HTTP tunnel) and register that URL with `jetemail webhooks create --url <public-url>`. You'll get real-time delivery identical to production, signature headers included.

## Related

* [Webhooks getting started](/webhooks/getting-started)
* [Event types](/webhooks/events)
* [Webhook security](/webhooks/security)