--- title: "Create a webhook" method: POST path: "/v2/webhooks" tags: ["Webhooks"] --- # Create a webhook `POST /v2/webhooks` 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](https://arize.com/docs/ax/rest-reference#api-version-stages). ## Request body - CreateWebhookRequest - `organization_id` string, required — A universally unique identifier (base64-encoded opaque string). - `name` string, required — Name of the webhook (must be unique within the organization) - `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` '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=` computed over `.`, where `` 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_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. - `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. ## Response `201` The created webhook. For `HMAC_SHA256` webhooks the response includes `signing_secret` — the only time it is ever returned. - CreateWebhookResponse — The created webhook, plus `signing_secret` for `HMAC_SHA256` webhooks — the only time the secret is ever returned. - `id` string, required — A universally unique identifier (base64-encoded opaque string). - `organization_id` string, required — A universally unique identifier (base64-encoded opaque string). - `name` string, required — Name of the webhook (unique within the organization) - `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` '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=` computed over `.`, where `` 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_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. - `timeout_ms` integer, required — How long a delivery request may run before it is abandoned, in milliseconds. Defaults to 30000. - `headers` object, required — Custom HTTP headers sent with each delivery request - `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 - `created_by_user_id` string — A universally unique identifier (base64-encoded opaque string). ## 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 --- [API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/revisions/4d95080d8ffb/schema)