{
"id": "V2ViaG9va1N1YnNjcmlwdGlvbjoxMjM0NQ==",
"webhook_id": "V2ViaG9vazoxMjM0NQ==",
"source_type": "PROMPT",
"source_id": "UHJvbXB0OjEyMzQ1",
"event": "PROMPT_VERSION_LABELED",
"created_at": "2026-08-01T12:00:00Z"
}{
"status": 400,
"title": "Invalid request parameters",
"detail": "The 'name' field is required and must be a non-empty string.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}{
"status": 401,
"title": "Authentication required",
"detail": "You must be authenticated to access this resource.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}{
"status": 403,
"title": "Access forbidden",
"detail": "You do not have permission to access this resource.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}{
"status": 404,
"title": "Resource not found",
"detail": "The requested resource with ID '12345' was not found.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}{
"status": 409,
"title": "Resource conflict",
"detail": "A resource with the given identifier already exists.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-conflict"
}{
"status": 422,
"title": "Unprocessable Entity",
"detail": "One or more fields failed validation.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}{
"status": 429,
"title": "Rate limit exceeded",
"detail": "You have exceeded the allowed number of requests. Please try again later.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}Create a webhook subscription
Subscribe a webhook to one event on a prompt, evaluator, evaluation
task, or space. To deliver several events to the same webhook, create
one subscription per event. A SPACE subscription covers every evaluation task in the
space, including tasks created later.
Payload Requirements
webhook_id,source_type,source_id, andeventare required.webhook_idmust be a webhook in the sourceās organization; unknown webhooks yield a 404.eventmust belong to the source type: prompt events forPROMPTsources, evaluator events forEVALUATORsources, andONLINE_TASK_RUN_FAILEDforONLINE_TASKandSPACEsources. Other combinations are rejected with a 422.- An
ONLINE_TASKsource must be an evaluation task; other task types are rejected with a 422. - A webhook can subscribe to a given event on a given source only once (409 on conflict).
- At most 200 webhooks may subscribe to the same event on a source; requests that would exceed this limit are rejected with a 422.
Creating a subscription requires PROMPT_UPDATE for a prompt source,
EVALUATOR_UPDATE for an evaluator source, PROJECT_EVAL_TASK_UPDATE
(or EXPERIMENT_EVAL_TASK_UPDATE for a dataset task) for a task source,
or a space, organization, or account admin role for a space source,
since a space subscription covers every task in the space, including
tasks in restricted projects. Callers who can read the source
(PROMPT_READ, EVALUATOR_READ, PROJECT_EVAL_TASK_READ or
EXPERIMENT_EVAL_TASK_READ) but lack the required permission receive
a 403; sources the caller cannot read yield a 404.
Checks run in this order, and the first failure is returned: request body validation (422), source access (404 or 403), source task type (422), webhook lookup (404), then duplicate subscription (409) and the per-source webhook limit (422).
{
"id": "V2ViaG9va1N1YnNjcmlwdGlvbjoxMjM0NQ==",
"webhook_id": "V2ViaG9vazoxMjM0NQ==",
"source_type": "PROMPT",
"source_id": "UHJvbXB0OjEyMzQ1",
"event": "PROMPT_VERSION_LABELED",
"created_at": "2026-08-01T12:00:00Z"
}{
"status": 400,
"title": "Invalid request parameters",
"detail": "The 'name' field is required and must be a non-empty string.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}{
"status": 401,
"title": "Authentication required",
"detail": "You must be authenticated to access this resource.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}{
"status": 403,
"title": "Access forbidden",
"detail": "You do not have permission to access this resource.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}{
"status": 404,
"title": "Resource not found",
"detail": "The requested resource with ID '12345' was not found.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}{
"status": 409,
"title": "Resource conflict",
"detail": "A resource with the given identifier already exists.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-conflict"
}{
"status": 422,
"title": "Unprocessable Entity",
"detail": "One or more fields failed validation.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}{
"status": 429,
"title": "Rate limit exceeded",
"detail": "You have exceeded the allowed number of requests. Please try again later.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}Authorizations
Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format
Service accounts may instead present an access token issued by an external identity provider (Microsoft Entra ID) when the account admin has configured that provider. Send it in the same header: Authorization: Bearer <access-token>.
Body
Body containing the webhook, the source to attach it to, and the event to deliver
Response
The created webhook subscription
A subscription delivers one event from one prompt, evaluator, task or space to one webhook. A webhook that should receive several events from the same resource has one subscription per event.
Was this page helpful?