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

# Update a webhook

`PATCH /v2/webhooks/{id}`

## Request

- Base URL: `https://api.village.ai`
- URL: `https://api.village.ai/v2/webhooks/{id}`
- Auth: HTTP bearer

Update a webhook by its encrypted id. Use this to point deliveries at a new URL, change which events are sent, rotate the signing secret (write-only — the new value is not echoed back, so keep what you set), or pause it by setting is_active to false — prefer pausing over deleting, since the webhook and its id survive. Send only the fields you want to change; anything omitted is left as-is. Two things to get right: `event_filter` is REPLACED, not merged, so send the complete list of event types you want, and passing `event_filter: null` widens the webhook to receive EVERY event type. Changing `url` redirects the user's data to a new destination, so confirm it with them first. Returns 404 if the webhook does not exist or belongs to someone else.

## Path parameters

- `id` string, required: Encrypted webhook identifier

## Request body

- UpdateWebhookRequest: Request body for updating a webhook. Every field is optional; supply at least one. Omitted fields are left unchanged.
  - `url` string, uri: HTTP(S) endpoint that receives the event payloads (HTTPS recommended). Must be publicly reachable and controlled by the user — localhost and private IP ranges are rejected.
  - `description` string: Human-readable label, so you can tell your webhooks apart later
  - `secret` string: Your own HMAC signing secret (min 32 characters), used to sign every delivery so your endpoint can verify it really came from Village. Leave this out and Village generates one for you; either way the secret is readable via this API.
  - `is_active` boolean: Set false to pause deliveries without deleting the webhook
  - `event_filter` string[], nullable: Event types this webhook receives. Pass null (or omit on create) to receive EVERY event type, including ones added in future. Pass an explicit array to narrow it.

## Response `200`

Webhook updated successfully

- object
  - `data` UpdateWebhookResponse, required: The webhook after the update
    - `id` string, required: Encrypted webhook identifier
    - `url` string, required: Endpoint that receives event payloads
    - `description` string, nullable, required: Human-readable label, or null if none was set
    - `is_active` boolean, required: True when the webhook is receiving deliveries; false when paused
    - `event_filter` string[], nullable, required: Event types delivered to this webhook. NULL means every event type is delivered.
    - `has_secret` boolean, required: Whether an HMAC signing secret is configured. The secret value is write-only — it is returned once by create_webhook and never again, so reads report only this flag.
    - `created_at` string, required: ISO 8601 creation timestamp
    - `updated_at` string, required: ISO 8601 last update timestamp
  - `metadata` object, required
    - `request_id` string, required

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - missing or invalid authentication
- `404`: Webhook not found

---

[API](https://skmtc.dev/village/apis/village-v2-api.md) - [All operations](https://skmtc.dev/village/apis/village-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/village/apis/village-v2-api/revisions/aebe21a1a544?raw)