--- title: "Create a webhook subscription" method: POST path: "/v2/webhook-subscriptions" tags: ["Webhooks"] --- # Create a webhook subscription `POST /v2/webhook-subscriptions` ## Request - Base URL: `https://api.arize.com` - URL: `https://api.arize.com/v2/webhook-subscriptions` - Auth: HTTP bearer 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`, and `event` are required. - `webhook_id` must be a webhook in the source's organization; unknown webhooks yield a 404. - `event` must belong to the source type: prompt events for `PROMPT` sources, evaluator events for `EVALUATOR` sources, and `ONLINE_TASK_RUN_FAILED` for `ONLINE_TASK` and `SPACE` sources. Other combinations are rejected with a 422. - An `ONLINE_TASK` source 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). This endpoint is in alpha, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages). ## Request body - CreateWebhookSubscriptionRequest - `webhook_id` string, required: A universally unique identifier (base64-encoded opaque string). - `source_type` 'PROMPT' | 'EVALUATOR' | 'ONLINE_TASK' | 'SPACE', required: The kind of resource a webhook subscription is attached to. - `PROMPT` — `source_id` is a prompt id. Prompt events apply. - `EVALUATOR` — `source_id` is an evaluator id. Evaluator events apply. - `ONLINE_TASK` — `source_id` is an evaluation task id. Task run events apply. - `SPACE` — `source_id` is a space id. Task run events apply to every evaluation task in the space, including tasks created later. - `source_id` string, required: A universally unique identifier (base64-encoded opaque string). - `event` 'PROMPT_VERSION_CREATED' | 'PROMPT_VERSION_LABELED' | 'PROMPT_VERSION_UNLABELED' | 'EVALUATOR_VERSION_CREATED' | 'ONLINE_TASK_RUN_FAILED', required: An event that a webhook can subscribe to. - `PROMPT_VERSION_CREATED` — a new version of the prompt was created. - `PROMPT_VERSION_LABELED` — a label was added to a version of the prompt. - `PROMPT_VERSION_UNLABELED` — a label was removed from a version of the prompt. - `EVALUATOR_VERSION_CREATED` — a new version of the evaluator was created. - `ONLINE_TASK_RUN_FAILED` — a run of an evaluation task failed, or wrote some evaluations and then stopped on an error. Sent once when a task starts failing and again each time the cause changes. Prompt events are valid only for `PROMPT` sources, evaluator events only for `EVALUATOR` sources, and task run events only for `ONLINE_TASK` and `SPACE` sources. ## Response `201` The created webhook subscription - WebhookSubscription: 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. - `id` string, required: A universally unique identifier (base64-encoded opaque string). - `webhook_id` string, required: A universally unique identifier (base64-encoded opaque string). - `source_type` 'PROMPT' | 'EVALUATOR' | 'ONLINE_TASK' | 'SPACE', required: The kind of resource a webhook subscription is attached to. - `PROMPT` — `source_id` is a prompt id. Prompt events apply. - `EVALUATOR` — `source_id` is an evaluator id. Evaluator events apply. - `ONLINE_TASK` — `source_id` is an evaluation task id. Task run events apply. - `SPACE` — `source_id` is a space id. Task run events apply to every evaluation task in the space, including tasks created later. - `source_id` string, required: A universally unique identifier (base64-encoded opaque string). - `event` 'PROMPT_VERSION_CREATED' | 'PROMPT_VERSION_LABELED' | 'PROMPT_VERSION_UNLABELED' | 'EVALUATOR_VERSION_CREATED' | 'ONLINE_TASK_RUN_FAILED', required: An event that a webhook can subscribe to. - `PROMPT_VERSION_CREATED` — a new version of the prompt was created. - `PROMPT_VERSION_LABELED` — a label was added to a version of the prompt. - `PROMPT_VERSION_UNLABELED` — a label was removed from a version of the prompt. - `EVALUATOR_VERSION_CREATED` — a new version of the evaluator was created. - `ONLINE_TASK_RUN_FAILED` — a run of an evaluation task failed, or wrote some evaluations and then stopped on an error. Sent once when a task starts failing and again each time the cause changes. Prompt events are valid only for `PROMPT` sources, evaluator events only for `EVALUATOR` sources, and task run events only for `ONLINE_TASK` and `SPACE` sources. - `created_at` string, date-time, required: Timestamp for when the subscription was created ## Other responses - `400`: Invalid request - `401`: Authentication is required - `403`: Insufficient permissions to access this resource - `404`: Not found - `409`: Resource conflict - `422`: Unprocessable entity - `429`: Rate limit exceeded ## Changes > 48 revisions in range; 1 not diffed. - **2026-10-23** `74723b1c4847`: 3 warning, 3 info - added the new `ONLINE_TASK` enum value to the `source_type/allOf[#/components/schemas/WebhookSourceType]/` response property for the response status `201` - added the new `ONLINE_TASK_RUN_FAILED` enum value to the `event/allOf[#/components/schemas/WebhookEventType]/` response property for the response status `201` - added the new `SPACE` enum value to the `source_type/allOf[#/components/schemas/WebhookSourceType]/` response property for the response status `201` - added the new `ONLINE_TASK` enum value to the request property `source_type/allOf[#/components/schemas/WebhookSourceType]/` - …2 more - **2026-09-12** `2a4c8244d07b`: 1 info - endpoint added [Operation history](https://skmtc.dev/arize-ai/apis/arize-rest-api/changes/v2/webhook-subscriptions/post.md) --- [API](https://skmtc.dev/arize-ai/apis/arize-rest-api.md) - [All operations](https://skmtc.dev/arize-ai/apis/arize-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/arize-ai/apis/arize-rest-api/revisions/22ad4acd3cbb?raw)