Webhooks

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

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.

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.

Create a Webhook

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

Bearer Auth

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

client.webhooks.delete_subscription(subscription_id="your-subscription-id")

print("Subscription deleted")

Skills

MCP server

API reference

API clients

Key Capabilities

Authentication Types

Event Types

List Webhooks

Create a Webhook

Bearer Auth

HMAC-SHA256 Auth

Get a Webhook

Update a Webhook

Delete a Webhook

Test a Webhook

List Delivery Attempts

Manage Subscriptions

List Subscriptions

Create a Subscription

Get a Subscription

Delete a Subscription

​Key Capabilities

​Authentication Types

​Event Types

​List Webhooks

​Create a Webhook

​Bearer Auth

​HMAC-SHA256 Auth

​Get a Webhook

​Update a Webhook

​Delete a Webhook

​Test a Webhook

​List Delivery Attempts

​Manage Subscriptions

​List Subscriptions

​Create a Subscription

​Get a Subscription

​Delete a Subscription

Key Capabilities

Authentication Types

Event Types

List Webhooks

Create a Webhook

Bearer Auth

HMAC-SHA256 Auth

Get a Webhook

Update a Webhook

Delete a Webhook

Test a Webhook

List Delivery Attempts

Manage Subscriptions

List Subscriptions

Create a Subscription

Get a Subscription

Delete a Subscription