curl --request POST \
  --url https://api.arize.com/v2/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "organization_id": "T3JnYW5pemF0aW9uOjEyMzQ1",
  "name": "Prompt release notifications",
  "url": "https://example.com/hooks/arize",
  "description": "Notifies the deploy pipeline when a prompt version is labeled",
  "auth_type": "HMAC_SHA256",
  "timeout_ms": 30000,
  "headers": {
    "X-Environment": "production"
  }
}
'

{
  "id": "V2ViaG9vazoxMjM0NQ==",
  "organization_id": "T3JnYW5pemF0aW9uOjEyMzQ1",
  "name": "Prompt release notifications",
  "description": "Notifies the deploy pipeline when a prompt version is labeled",
  "url": "https://example.com/hooks/arize",
  "auth_type": "HMAC_SHA256",
  "signing_secret": "whsec_dGhpc0lzQW5FeGFtcGxlU2VjcmV0VmFsdWVhYmNk",
  "signing_secret_hint": "whsec_…abcd",
  "timeout_ms": 30000,
  "headers": {
    "X-Environment": "production"
  },
  "created_at": "2026-08-01T12:00:00Z",
  "updated_at": "2026-08-01T12:00:00Z",
  "created_by_user_id": "VXNlcjoxMjM0NQ=="
}

Webhooks

Create a webhook

Create a new webhook in an organization.

Payload Requirements

organization_id, name, and url are required.
The webhook name must be unique within the organization (409 on conflict).
auth_type is optional, defaults to BEARER, and cannot be changed after creation.
auth_token is only valid when auth_type is BEARER, and is write-only — it is never returned in any response.
timeout_ms is optional, defaults to 30000, and must be between 1000 and 60000.
headers is optional and holds at most 20 entries; header names must be valid HTTP header names, and connection-management headers are rejected.
System-managed fields (id, created_at, updated_at) are generated automatically and rejected if provided.

For HMAC_SHA256 webhooks, a signing secret is generated and returned in this response — the only time it is ever returned. Store it securely: only a redacted hint is readable afterwards, and losing the secret means deleting and recreating the webhook.

This endpoint is in alpha, read more here.

POST

webhooks

curl --request POST \
  --url https://api.arize.com/v2/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "organization_id": "T3JnYW5pemF0aW9uOjEyMzQ1",
  "name": "Prompt release notifications",
  "url": "https://example.com/hooks/arize",
  "description": "Notifies the deploy pipeline when a prompt version is labeled",
  "auth_type": "HMAC_SHA256",
  "timeout_ms": 30000,
  "headers": {
    "X-Environment": "production"
  }
}
'

{
  "id": "V2ViaG9vazoxMjM0NQ==",
  "organization_id": "T3JnYW5pemF0aW9uOjEyMzQ1",
  "name": "Prompt release notifications",
  "description": "Notifies the deploy pipeline when a prompt version is labeled",
  "url": "https://example.com/hooks/arize",
  "auth_type": "HMAC_SHA256",
  "signing_secret": "whsec_dGhpc0lzQW5FeGFtcGxlU2VjcmV0VmFsdWVhYmNk",
  "signing_secret_hint": "whsec_…abcd",
  "timeout_ms": 30000,
  "headers": {
    "X-Environment": "production"
  },
  "created_at": "2026-08-01T12:00:00Z",
  "updated_at": "2026-08-01T12:00:00Z",
  "created_by_user_id": "VXNlcjoxMjM0NQ=="
}

Authorizations

Authorization

string

header

required

Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format

Body

application/json

Body containing webhook creation parameters

organization_id

string

required

The unique identifier of the organization to create the webhook in

Example:

"RW50aXR5OjEyMzQ1"

name

string

required

Name of the webhook (must be unique within the organization)

Maximum string length: 255

url

string<uri>

required

The HTTPS endpoint events are delivered to

description

string

A brief description of the webhook's purpose. Defaults to an empty string if omitted.

auth_type

enum<string>

How deliveries from this webhook are authenticated. Defaults to BEARER if omitted, and cannot be changed after creation. For HMAC_SHA256, a signing secret is generated for you and returned once in the create response.

Available options:

BEARER,

HMAC_SHA256

auth_token

string

The complete Authorization header value sent with each delivery request, e.g. Bearer my-token. Sent verbatim — include the Bearer prefix if your endpoint expects one. Only valid when auth_type is BEARER. Write-only: never returned in any response.

timeout_ms

integer

How long a delivery request may run before it is abandoned, in milliseconds. Defaults to 30000 if omitted.

Required range: 1000 <= x <= 60000

headers

object

Custom HTTP headers sent with each delivery request, as a map of at most 20 header names to values. Header names must be valid HTTP header names; connection-management headers (e.g. Host, Content-Length) are rejected.

Show child attributes

Response

The created webhook. For HMAC_SHA256 webhooks the response includes signing_secret — the only time it is ever returned.

The created webhook, plus signing_secret for HMAC_SHA256 webhooks — the only time the secret is ever returned.

string

required

Unique identifier for the webhook

Example:

"RW50aXR5OjEyMzQ1"

organization_id

string

required

The unique identifier of the organization that owns the webhook

Example:

"RW50aXR5OjEyMzQ1"

name

string

required

Name of the webhook (unique within the organization)

Maximum string length: 255

description

string

required

A brief description of the webhook's purpose. Defaults to an empty string.

url

string<uri>

required

The HTTPS endpoint events are delivered to

auth_type

enum<string>

required

How deliveries from this webhook are authenticated. Fixed at creation.

Available options:

BEARER,

HMAC_SHA256

timeout_ms

integer

required

How long a delivery request may run before it is abandoned, in milliseconds. Defaults to 30000.

Required range: 1000 <= x <= 60000

headers

object

required

Custom HTTP headers sent with each delivery request

Show child attributes

created_at

string<date-time>

required

Timestamp for when the webhook was created

updated_at

string<date-time>

required

Timestamp for when the webhook was last updated

signing_secret

string

The secret used to verify delivery signatures. Only returned once, in this response, when auth_type is HMAC_SHA256. Store it securely — it cannot be retrieved again; only a redacted hint (signing_secret_hint) is readable afterwards. Absent for BEARER webhooks.

signing_secret_hint

string

Redacted hint of the signing secret (e.g. whsec_…abcd), useful for identifying which secret the webhook uses. Present only for HMAC_SHA256 webhooks.

created_by_user_id

string

The unique identifier of the user who created the webhook. Absent when that user has since been removed from the account.

Example:

"RW50aXR5OjEyMzQ1"

⌘I

API reference

API clients

Create a webhook

Authorizations

Body

Response