Sign in

1103033ea050

latestOpenAPI 3.0.3Apache-2.02026-08-12131380648.1 KB
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.

<Warning>This endpoint is in alpha, read more here.</Warning>

post/v2/webhooks

Request body

organization_idstring required

A universally unique identifier (base64-encoded opaque string).

namestring required

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

urlstring uri required

The HTTPS endpoint events are delivered to

descriptionstring

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

auth_type'BEARER' | 'HMAC_SHA256'

How deliveries from this webhook are authenticated.

  • BEARER: the stored auth_token is sent verbatim as the Authorization header of each delivery request.
  • HMAC_SHA256: each delivery is signed with the webhook's signing secret. The X-Arize-Webhook-Signature header carries v1=<hex-encoded HMAC-SHA256> computed over <timestamp>.<raw request body>, where <timestamp> is the Unix-seconds value from the X-Arize-Webhook-Timestamp header and the raw body is the exact bytes received. Deliveries also carry X-Arize-Webhook-Id (event identifier) and X-Arize-Webhook-Event (event type). To verify, recompute the HMAC over the received timestamp and raw body with your stored secret and compare it to the signature.
auth_tokenstring

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_msinteger

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

headersobject

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.

Example request

{
  "organization_id": "RW50aXR5OjEyMzQ1"
}

Response

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

idstring required

A universally unique identifier (base64-encoded opaque string).

organization_idstring required

A universally unique identifier (base64-encoded opaque string).

namestring required

Name of the webhook (unique within the organization)

descriptionstring required

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

urlstring uri required

The HTTPS endpoint events are delivered to

auth_type'BEARER' | 'HMAC_SHA256' required

How deliveries from this webhook are authenticated.

  • BEARER: the stored auth_token is sent verbatim as the Authorization header of each delivery request.
  • HMAC_SHA256: each delivery is signed with the webhook's signing secret. The X-Arize-Webhook-Signature header carries v1=<hex-encoded HMAC-SHA256> computed over <timestamp>.<raw request body>, where <timestamp> is the Unix-seconds value from the X-Arize-Webhook-Timestamp header and the raw body is the exact bytes received. Deliveries also carry X-Arize-Webhook-Id (event identifier) and X-Arize-Webhook-Event (event type). To verify, recompute the HMAC over the received timestamp and raw body with your stored secret and compare it to the signature.
signing_secretstring

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_hintstring

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

timeout_msinteger required

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

headersobject required

Custom HTTP headers sent with each delivery request

created_atstring date-time required

Timestamp for when the webhook was created

updated_atstring date-time required

Timestamp for when the webhook was last updated

created_by_user_idstring

A universally unique identifier (base64-encoded opaque string).

Example response

{
  "id": "RW50aXR5OjEyMzQ1",
  "organization_id": "RW50aXR5OjEyMzQ1",
  "created_by_user_id": "RW50aXR5OjEyMzQ1"
}