---
title: "Update a webhook configuration"
description: "Replaces mutable webhook configuration fields. `name` and `url` are required. Omitted secret and headers are cleared. Omitted isActive preserves the current status. Enabling requires a successful test of the same configuration within 15 minutes."
canonical: https://y2.dev/docs/api/reference/webhooks/updateWebhook/
---

Endpoint Reference[Webhooks](https://y2.dev/docs/api/reference/webhooks)

# Update a webhook configuration

Replaces mutable webhook configuration fields. \`name\` and \`url\` are required. Omitted secret and headers are cleared. Omitted isActive preserves the current status. Enabling requires a successful test of the same configuration within 15 minutes.

`PUT https://api.y2.dev/api/v1/webhooks/{webhookId}`

- Operation ID: `updateWebhook`
- Required scopes: `webhooks:manage`
- Contract: https://y2.dev/openapi.json

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookId` | path | string | Yes | Stable public webhook configuration ID. |
| `If-Match` | header | string | No | Strong ETag from the latest representation. A mismatch returns 412. |

## Request body

`application/json`: `WebhookReplaceRequest` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Webhook display name |
| `url` | string (uri) | Yes | Webhook endpoint URL (must be HTTPS) |
| `secret` | string | No | Shared secret for signature verification |
| `headers` | object | No | Custom headers to include in webhook deliveries |
| `isActive` | boolean | No |  |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Webhook configuration updated | `WebhookUpdateResponse` |
| 400 | Invalid request parameters |  |
| 401 | Missing or invalid API key |  |
| 403 | Insufficient permissions or access denied |  |
| 404 | Resource not found |  |
| 409 | WEBHOOK_TEST_REQUIRED: test the current configuration successfully before enabling. |  |
| 412 | The supplied If-Match validator does not match the current representation. |  |
| 429 | Rate limit exceeded (per-key or per-account aggregate) |  |
| 500 | Internal server error |  |

### 200 response fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | `WebhookConfig` |  |
| `data.id` | string | Stable public webhook configuration ID |
| `data.type` | string |  |
| `data.name` | string | Webhook display name |
| `data.url` | string (uri) | Webhook endpoint URL |
| `data.status` | `active`, `disabled` |  |
| `data.signing` | object |  |
| `data.customHeaders[]` | array of string | Configured header names. Values are never returned. |
| `data.deliveryHealth` | object |  |
| `data.createdAt` | string (date-time) |  |
| `data.updatedAt` | string (date-time) |  |
| `data.links` | object |  |
| `meta` | object |  |
| `meta.message` | string |  |
