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

# Webhooks

> Manage webhooks and their subscriptions with the AX CLI

<Note>
  The `ax webhooks` commands are currently in **ALPHA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

The `ax webhooks` commands let you create and manage webhooks and their prompt and evaluator subscriptions on the Arize platform. A webhook delivers platform events to an HTTPS endpoint; subscriptions control which prompt or evaluator events each webhook receives.

## `ax webhooks list`

List webhooks you have access to, most recently created first.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks list [--organization <name_or_id>] [--name <filter>] [--limit <n>] [--cursor <cursor>] [--output <fmt>] [--verbose]
```

| Option | Description |
| - | - |
| `--organization` | Organization name or ID to narrow the list |
| `--name`, `-n` | Filter by webhook name (case-insensitive substring match) |
| `--limit`, `-l` | Maximum number of webhooks to return (1-100, default: 15) |
| `--cursor`, `-c` | Pagination cursor for the next page |
| `--output`, `-o` | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks list
ax webhooks list --organization org_abc123 --name "prod" --output webhooks.json
```

## `ax webhooks get`

Get a webhook by name or ID. Credentials (auth token, header values, signing secret) are never returned.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks get <name-or-id> [--organization <name_or_id>] [--output <fmt>] [--verbose]
```

| Option | Description |
| - | - |
| `--organization` | Organization name or ID (required when using a webhook name instead of ID) |
| `--output`, `-o` | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks get wh_abc123
ax webhooks get "prod-webhook" --organization org_abc123
```

## `ax webhooks create`

Create a webhook. For `HMAC_SHA256` webhooks the signing secret is printed once after creation and never again; store it securely. `BEARER` webhooks have no secret to show.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks create --organization <name_or_id> --name <name> --url <url> [options] [--output <fmt>] [--verbose]
```

| Option | Description |
| - | - |
| `--organization` | Organization name or ID to create the webhook in (required) |
| `--name`, `-n` | Webhook name (unique within the organization, max 255 characters) (required) |
| `--url` | HTTPS endpoint events are delivered to (required) |
| `--description` | Optional description |
| `--auth-type` | How deliveries are authenticated: `BEARER` or `HMAC_SHA256` (default: `BEARER`). Cannot be changed after creation. |
| `--auth-token` | Complete `Authorization` header value sent verbatim with each delivery, e.g. `'Bearer my-token'`. `BEARER` only; never returned. |
| `--timeout-ms` | Delivery timeout in milliseconds (1000-60000, default: 30000) |
| `--header` | Custom header sent with each delivery as `KEY=VALUE` (repeat for multiple) |
| `--output`, `-o` | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs |

<Warning>
  For `HMAC_SHA256` webhooks, the signing secret is displayed once after creation. Save it securely — it will not be shown again.
</Warning>

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# Bearer-authenticated webhook
ax webhooks create \
  --organization org_abc123 \
  --name "prod-webhook" \
  --url https://example.com/hooks/arize \
  --auth-type BEARER \
  --auth-token "Bearer my-token"

# HMAC-signed webhook with a custom header
ax webhooks create \
  --organization org_abc123 \
  --name "signed-webhook" \
  --url https://example.com/hooks/arize \
  --auth-type HMAC_SHA256 \
  --header "X-Env=prod"
```

## `ax webhooks update`

Update a webhook by name or ID. Only the options you pass are sent; omitted fields are left unchanged. At least one option must be given. The auth type cannot be changed and an HMAC signing secret cannot be rotated — create a new webhook instead.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks update <name-or-id> [--organization <name_or_id>] [options] [--output <fmt>] [--verbose]
```

| Option | Description |
| - | - |
| `--organization` | Organization name or ID (required when using a webhook name instead of ID) |
| `--name`, `-n` | New webhook name |
| `--description` | New description. Pass `""` (empty string) to clear. |
| `--url` | New HTTPS endpoint |
| `--auth-token` | Replacement `Authorization` header value. `BEARER` webhooks only; never returned. |
| `--timeout-ms` | New delivery timeout in milliseconds (1000-60000) |
| `--header` | Replacement custom header as `KEY=VALUE` (repeat for multiple). Replaces the whole header map. |
| `--clear-headers` | Remove every custom header. Cannot be combined with `--header`. |
| `--output`, `-o` | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks update wh_abc123 --url https://example.com/hooks/arize/v2
ax webhooks update wh_abc123 --header "X-Env=staging" --header "X-Team=ml"
ax webhooks update wh_abc123 --clear-headers
```

## `ax webhooks delete`

Delete a webhook by name or ID. The webhook is detached from every prompt, evaluator, and monitor it was subscribed to. This operation is irreversible.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks delete <name-or-id> [--organization <name_or_id>] [--force] [--verbose]
```

| Option | Description |
| - | - |
| `--organization` | Organization name or ID (required when using a webhook name instead of ID) |
| `--force`, `-f` | Skip the confirmation prompt |
| `--verbose`, `-v` | Enable verbose logs |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks delete wh_abc123
ax webhooks delete "prod-webhook" --organization org_abc123 --force
```

## `ax webhooks test`

Send a test event to a webhook's endpoint and report the outcome. Prints the endpoint's `status_code` and `error_message`, then exits non-zero when the status is not 2xx (`status_code` is 502 when no response was received). Not supported for `HMAC_SHA256` webhooks.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks test <name-or-id> [--organization <name_or_id>] [--output <fmt>] [--verbose]
```

| Option | Description |
| - | - |
| `--organization` | Organization name or ID (required when using a webhook name instead of ID) |
| `--output`, `-o` | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs |

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks test wh_abc123
```

## `ax webhooks deliveries`

List a webhook's delivery attempts, most recent first. Failed deliveries are retried, so one event may have several attempts.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks deliveries <name-or-id> [--organization <name_or_id>] [--limit <n>] [--cursor <cursor>] [--output <fmt>] [--verbose]
```

| Option | Description |
| - | - |
| `--organization` | Organization name or ID (required when using a webhook name instead of ID) |
| `--limit`, `-l` | Maximum number of delivery attempts to return (1-500, default: 15) |
| `--cursor`, `-c` | Pagination cursor for the next page |
| `--output`, `-o` | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs |

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks deliveries wh_abc123 --limit 50
```

## `ax webhooks subscriptions list`

List webhook subscriptions, optionally narrowed to one prompt or evaluator. Each subscription delivers one event to one webhook, so a webhook that receives several events appears once per event.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks subscriptions list [--source-type <type>] [--source-id <id>] [--limit <n>] [--cursor <cursor>] [--output <fmt>] [--verbose]
```

| Option | Description |
| - | - |
| `--source-type` | Kind of source to list subscriptions for: `PROMPT` or `EVALUATOR`. Requires `--source-id`. |
| `--source-id` | ID of the prompt or evaluator. Requires `--source-type`. |
| `--limit`, `-l` | Maximum number of subscriptions to return (1-100, default: 15) |
| `--cursor`, `-c` | Pagination cursor for the next page |
| `--output`, `-o` | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks subscriptions list
ax webhooks subscriptions list --source-type PROMPT --source-id pr_abc123
```

## `ax webhooks subscriptions create`

Subscribe a webhook to one event on a prompt or evaluator. Run once per event to deliver several events to the same webhook. Prompt events go with `PROMPT` sources and evaluator events with `EVALUATOR` sources.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks subscriptions create --webhook <name_or_id> --source-type <type> --source-id <id> --event <event> [--organization <name_or_id>] [--output <fmt>] [--verbose]
```

| Option | Description |
| - | - |
| `--webhook` | Webhook name or ID (required) |
| `--source-type` | Kind of source to subscribe to: `PROMPT` or `EVALUATOR` (required) |
| `--source-id` | ID of the prompt or evaluator (required) |
| `--event` | Event to deliver: `PROMPT_VERSION_CREATED`, `PROMPT_VERSION_LABELED`, `PROMPT_VERSION_UNLABELED`, or `EVALUATOR_VERSION_CREATED` (required) |
| `--organization` | Organization name or ID (required when using a webhook name instead of ID) |
| `--output`, `-o` | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs |

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks subscriptions create \
  --webhook wh_abc123 \
  --source-type PROMPT \
  --source-id pr_abc123 \
  --event PROMPT_VERSION_CREATED
```

## `ax webhooks subscriptions get`

Get a webhook subscription by ID.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks subscriptions get <subscription-id> [--output <fmt>] [--verbose]
```

| Option | Description |
| - | - |
| `--output`, `-o` | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs |

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks subscriptions get sub_abc123
```

## `ax webhooks subscriptions delete`

Delete a webhook subscription by ID. The webhook stops receiving that event from the source. Other subscriptions and the webhook itself are unaffected.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks subscriptions delete <subscription-id> [--force] [--verbose]
```

| Option | Description |
| - | - |
| `--force`, `-f` | Skip the confirmation prompt |
| `--verbose`, `-v` | Enable verbose logs |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax webhooks subscriptions delete sub_abc123
ax webhooks subscriptions delete sub_abc123 --force
```