# PATCH /v1/webhooks/{webhookId}

**Service:** Webhooks  
**Operation:** `WebhookService_UpdateWebhook`

Fields left unset keep their current value. The secret cannot be changed (rotation is not available in v1); to stop deliveries set status to disabled, to retire an endpoint delete the subscription and create a new one.

## Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookId` | path | string | yes | The subscription to change. |

## Request body

`UpdateWebhookBody` (application/json)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | A new HTTPS endpoint. Same validation as at create. |
| `eventTypes` | string[] | no | A replacement event-type list (full replacement, not a merge). At least one when provided. |
| `description` | string | no | A new description. |
| `status` | WebhookStatus | no | Enable or disable deliveries. Re-enabling an auto-disabled subscription resumes deliveries of NEW events; exhausted deliveries are not revived. The lifecycle state of a webhook subscription.   - WEBHOOK_STATUS_ENABLED: The subscription receives deliveries.  - WEBHOOK_STATUS_DISABLED: The subscription receives no deliveries. Set manually via UpdateWebhook, or automatically when deliveries exhaust their retries and nothing has been delivered successfully for 7 days (auto-disable; re-enable via UpdateWebhook once the endpoint is healthy). One of: WEBHOOK_STATUS_UNSPECIFIED, WEBHOOK_STATUS_ENABLED, WEBHOOK_STATUS_DISABLED. |

## Responses

| Status | Schema | Description |
| --- | --- | --- |
| 200 | `UpdateWebhookResponse` | A successful response. |
| 400 | `Error` | The request was rejected because it was malformed — for example a non-HTTPS url, an endpoint resolving to private address space, an unknown event type (the message names it), or an empty event-type list. The body is a validation-failure envelope: an overall type and message and one entry per problem (each with a stable code, a message, and a param pointing at the offending parameter). |
| 401 | `Error` | The request is missing a valid bearer token, or the token is invalid or expired. |
| 403 | `Error` | The token is valid but does not permit this action, or the resource belongs to a company the token cannot act for. The error type is permission_denied. |
| 404 | `Error` | No webhook subscription with the given id exists for the authenticated company. |
| 429 | `Error` | The request was throttled (rate_limited) or exceeded a size limit (resource_exhausted). When throttled, the Retry-After header says how many seconds to wait before retrying; a resource_exhausted request will fail the same way if retried unchanged. |
| default | `Error` | Any other error. The body is the same error envelope every error uses: a short stable type identifying the kind of failure, a human-readable message, and the request's idempotency key echoed back when one was supplied. |

## Returns

`UpdateWebhookResponse`

| Field | Type | Description |
| --- | --- | --- |
| `webhook` | Webhook | The subscription after the change. secret is never populated here. |
| `webhook.webhookId` | string | The subscription's id. Read-only. |
| `webhook.url` | string | The HTTPS endpoint deliveries are POSTed to. Plain http URLs and endpoints resolving to private address space are rejected at create and update time. |
| `webhook.eventTypes` | string[] | The event types this subscription receives. At least one. Valid values are the v1 taxonomy: `order.created`, `order.updated`, `order.status_changed`, `order.archived`, `quote.created`, `quote.updated`, `quote.status_changed`, `quote.converted_to_order`. Unknown values are rejected naming the offender. |
| `webhook.status` | WebhookStatus | Whether the subscription is receiving deliveries. New subscriptions are enabled; see WebhookStatus for how a subscription becomes disabled. The lifecycle state of a webhook subscription.   - WEBHOOK_STATUS_ENABLED: The subscription receives deliveries.  - WEBHOOK_STATUS_DISABLED: The subscription receives no deliveries. Set manually via UpdateWebhook, or automatically when deliveries exhaust their retries and nothing has been delivered successfully for 7 days (auto-disable; re-enable via UpdateWebhook once the endpoint is healthy). One of: WEBHOOK_STATUS_UNSPECIFIED, WEBHOOK_STATUS_ENABLED, WEBHOOK_STATUS_DISABLED. |
| `webhook.description` | string | A free-form label for your own bookkeeping. |
| `webhook.secret` | string | The signing secret, in the form `whsec_<43 base64url characters>`. Returned ONLY in the CreateWebhook response — store it then; it cannot be retrieved again (rotation is not available in v1). The FULL string, prefix included, is the HMAC-SHA256 key for verifying the X-Factory-Signature header on deliveries. |
| `webhook.createdAt` | string | When the subscription was created. Read-only. |
| `webhook.updatedAt` | string | When the subscription was last changed. Read-only. |

---

Source: https://developer.factory.app/reference/webhooks/update-webhook · Factory Sales API v1