---
title: "Update a webhook"
method: PATCH
path: "/v2/webhooks/{webhook_id}"
tags: ["Webhooks"]
---

# Update a webhook

`PATCH /v2/webhooks/{webhook_id}`

Update a webhook by its ID. At least one field must be provided.

**Payload Requirements**
- At least one of `name`, `description`, `url`, `auth_token`,
  `timeout_ms`, or `headers` must be provided.
- If `name` is provided, it must be unique within the organization
  (409 on conflict).
- `headers` replaces the whole header map.
- `auth_type` cannot be changed after creation, and the signing secret
  of an `HMAC_SHA256` webhook cannot be rotated — create a new webhook
  instead.
- System-managed fields (`id`, `created_at`, `updated_at`) cannot be
  modified.

<Warning>This endpoint is in alpha, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Warning>

## Path parameters

- `webhook_id` string, required — A universally unique identifier (base64-encoded opaque string).

## Request body

- UpdateWebhookRequest
  - `name` string — Updated name of the webhook (must be unique within the organization)
  - `description` string, nullable — Updated description of the webhook. Set to `null` to clear it.
  - `url` string, uri — Updated HTTPS endpoint events are delivered to
  - `auth_token` string — Replacement `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 the webhook's `auth_type` is `BEARER`. Write-only: never returned in any response.
  - `timeout_ms` integer — Updated delivery timeout in milliseconds
  - `headers` object — Replacement custom HTTP headers, as a map of at most 20 header names to values. Replaces the whole header map; headers not included are removed.

## Response `200`

A webhook object

- Webhook — A webhook is an organization-owned destination that receives event deliveries over HTTPS. Attach a webhook to prompts and evaluators through their webhook-subscription endpoints to choose which events it receives. Credentials are write-only: the bearer token is never returned, and the HMAC signing secret is returned exactly once, in the create response — only its redacted hint is readable afterwards.
  - `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=<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_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. The full secret is returned exactly once, in the create response, and cannot be retrieved afterwards.
  - `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)