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

> Create and manage webhooks and subscriptions that deliver prompt and evaluator events to your HTTPS endpoints.

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

Manage webhooks and their subscriptions programmatically. A webhook is an organization-level destination — an HTTPS endpoint plus the authentication used to call it. A subscription delivers one event from one prompt or evaluator to one webhook.

## Key Capabilities

* List, create, retrieve, update, and delete organization-level webhooks
* Send a test event and inspect delivery attempts
* Subscribe a webhook to prompt or evaluator events
* List, retrieve, and delete subscriptions

## Authentication Types

| `WebhookAuthType` value | Description                                                               |
| ----------------------- | ------------------------------------------------------------------------- |
| `BEARER`                | Sends a fixed `Authorization` header value with each delivery (default)   |
| `HMAC_SHA256`           | Signs each delivery; the signing secret is returned only once at creation |

## Event Types

| `WebhookEventType` value    | Source type |
| --------------------------- | ----------- |
| `PROMPT_VERSION_CREATED`    | `PROMPT`    |
| `PROMPT_VERSION_LABELED`    | `PROMPT`    |
| `PROMPT_VERSION_UNLABELED`  | `PROMPT`    |
| `EVALUATOR_VERSION_CREATED` | `EVALUATOR` |

## List Webhooks

List webhooks you have access to, newest-first, with optional filtering by organization or name.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
resp = client.webhooks.list(
    organization="your-org-name-or-id",  # optional
    name="deploys",                       # optional substring filter
    limit=50,
)

for webhook in resp.webhooks:
    print(webhook.id, webhook.name, webhook.url)
```

For details on pagination, field introspection, and data conversion (to dict/JSON/DataFrame), see [Response Objects](/docs/api-clients/python/version-8/overview#response-objects).

## Create a Webhook

Create a webhook in an organization. Webhook names must be unique within the organization.

### Bearer Auth

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from arize.webhooks.types import WebhookAuthType

result = client.webhooks.create(
    organization="your-org-name-or-id",
    name="deploy-notifications",
    url="https://hooks.example.com/arize",
    description="Notifies our deploy pipeline",  # optional
    auth_type=WebhookAuthType.BEARER,            # optional; defaults to BEARER
    auth_token="Bearer my-token",                # sent verbatim as the Authorization header
    timeout_ms=30000,                             # optional; 1000–60000, defaults to 30000
    headers={"X-Env": "prod"},                    # optional; at most 20 headers
)

print(result.id, result.name)
```

### HMAC-SHA256 Auth

<Warning>
  For `HMAC_SHA256` webhooks, the `signing_secret` is returned **only once** in the create response. Store it securely — it cannot be retrieved again, and losing it means deleting and recreating the webhook.
</Warning>

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from arize.webhooks.types import WebhookAuthType

result = client.webhooks.create(
    organization="your-org-name-or-id",
    name="signed-webhook",
    url="https://hooks.example.com/arize",
    auth_type=WebhookAuthType.HMAC_SHA256,
)

print(result.signing_secret)  # store securely — shown only once
print(result.signing_secret_hint)
```

## Get a Webhook

Retrieve a webhook by ID or name. When resolving by name, pass `organization`. Credentials (`auth_token`, header values, signing secret) are never included.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
webhook = client.webhooks.get(
    webhook="your-webhook-name-or-id",
    organization="your-org-name-or-id",  # required when using a name
)

print(webhook.id, webhook.name, webhook.url)
```

## Update a Webhook

Only the fields you pass are updated. At least one field must be provided. `auth_type` cannot be changed after creation, and an `HMAC_SHA256` webhook's signing secret cannot be rotated — create a new webhook instead. Pass `description=None` to clear the description. Providing `headers` replaces the entire header map.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
webhook = client.webhooks.update(
    webhook="your-webhook-name-or-id",
    organization="your-org-name-or-id",  # required when using a name
    name="deploy-notifications-v2",
    url="https://hooks.example.com/arize/v2",
)

print(webhook.name)
```

## Delete a Webhook

Delete a webhook by ID or name. It stops receiving events and is detached from every prompt, evaluator, and monitor it was subscribed to. This operation is irreversible. There is no response from this call.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
client.webhooks.delete(
    webhook="your-webhook-name-or-id",
    organization="your-org-name-or-id",  # required when using a name
)

print("Webhook deleted")
```

## Test a Webhook

Send a test event to a webhook's endpoint and report the outcome. A successful call means the test ran — inspect `status_code` and `error_message` for the endpoint's actual response. `status_code` is `502` when no response was received. Test deliveries are not supported for `HMAC_SHA256` webhooks.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
result = client.webhooks.test(
    webhook="your-webhook-name-or-id",
    organization="your-org-name-or-id",  # required when using a name
)

print(result.status_code, result.error_message)
```

## List Delivery Attempts

List a webhook's delivery attempts, most recent first. Each event may have several attempts, since failed deliveries are retried.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
resp = client.webhooks.list_delivery_attempts(
    webhook="your-webhook-name-or-id",
    organization="your-org-name-or-id",  # required when using a name
    limit=50,
)

for attempt in resp.delivery_attempts:
    print(attempt.event_id, attempt.attempt_number, attempt.status_code)
```

For details on pagination, field introspection, and data conversion (to dict/JSON/DataFrame), see [Response Objects](/docs/api-clients/python/version-8/overview#response-objects).

## Manage Subscriptions

A subscription delivers one event from one prompt or evaluator to one webhook. To deliver several events to the same webhook, create one subscription per event.

### List Subscriptions

List subscriptions, newest-first. To filter to a single source, pass `source_type` and `source_id` together.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from arize.webhooks.types import WebhookSourceType

resp = client.webhooks.list_subscriptions(
    source_type=WebhookSourceType.PROMPT,  # optional; must be paired with source_id
    source_id="your-prompt-id",            # optional; must be paired with source_type
    limit=50,
)

for subscription in resp.subscriptions:
    print(subscription.id, subscription.webhook_id, subscription.event)
```

### Create a Subscription

Subscribe a webhook to one event on a prompt or evaluator. The event must belong to the source type: prompt events for `PROMPT` sources and evaluator events for `EVALUATOR` sources.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from arize.webhooks.types import WebhookEventType, WebhookSourceType

subscription = client.webhooks.create_subscription(
    webhook="your-webhook-name-or-id",
    organization="your-org-name-or-id",  # required when webhook is a name
    source_type=WebhookSourceType.PROMPT,
    source_id="your-prompt-id",
    event=WebhookEventType.PROMPT_VERSION_CREATED,
)

print(subscription.id)
```

### Get a Subscription

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
subscription = client.webhooks.get_subscription(subscription_id="your-subscription-id")

print(subscription.webhook_id, subscription.event)
```

### Delete a Subscription

Delete a subscription by ID. The webhook stops receiving that event from the source. Other subscriptions and the webhook itself are unaffected. There is no response from this call.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
client.webhooks.delete_subscription(subscription_id="your-subscription-id")

print("Subscription deleted")
```