# Update a webhook endpoint

> The webhook_endpoints.update operation: PATCH /api/v1/webhook_endpoints/{id} in the REST API and the webhook_endpoints_update tool in the MCP server.

Changes an endpoint's URL, event types, description or metadata, or disables or enables it. Send only the
fields to change; `metadata` replaces the whole set.

- `enabled: false` stops deliveries: event deliveries waiting for a retry are canceled instead of sent.
- `enabled: true` resumes deliveries of new events, also after Ownrecord disabled the endpoint for failing for
  3 days. Events that happened while it was disabled aren't sent again on their own: redeliver them with
  `webhook_deliveries.redeliver`.

The signing secret doesn't change (use `webhook_endpoints.rotate_secret`).

## At a glance

- **REST:** `PATCH /api/v1/webhook_endpoints/{id}`
- **MCP tool:** `webhook_endpoints_update`
- **Operation ID:** `webhook_endpoints.update`
- **Scope:** Brand
- **Permission:** `webhooks:admin`
- **Risk tier:** `security`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` optional
- **Modes:** Test and live
- **Authentication:** API key with the `webhooks:admin` scope
- **Since:** M4

## Request

### Path parameters

| Field | Type      | Description |
| ----- | --------- | ----------- |
| `id`  | `we_…` ID |             |

### Body

A JSON object (`Content-Type: application/json`):

| Field         | Type            | Required | Description                                                                                 |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------- |
| `url`         | string          | No       | The https URL Ownrecord POSTs events to, e.g. <https://example.com/webhooks/ownrecord>.     |
| `events`      | array of string | No       | Event types to receive (from the event catalogue), or \["\*"] for every event of the brand. |
| `description` | string or null  | No       | A new description, or null to remove it.                                                    |
| `enabled`     | boolean         | No       | false stops deliveries (waiting retries are canceled); true resumes them.                   |
| `metadata`    | object          | No       | Your own key-value pairs (at most 50 keys). On updates the whole set is replaced.           |

## Response

`200 OK` with a JSON object:

| Field                     | Type                               | Description |
| ------------------------- | ---------------------------------- | ----------- |
| `id`                      | `we_…` ID                          |             |
| `object`                  | `"webhook_endpoint"`               |             |
| `brandId`                 | `brd_…` ID                         |             |
| `livemode`                | boolean                            |             |
| `url`                     | string                             |             |
| `description`             | string or null                     |             |
| `events`                  | array of string                    |             |
| `enabled`                 | boolean                            |             |
| `disabledReason`          | one of `manual`, `failing` or null |             |
| `disabledAt`              | date-time or null                  |             |
| `failingSince`            | date-time or null                  |             |
| `secretRotatedAt`         | date-time or null                  |             |
| `previousSecretExpiresAt` | date-time or null                  |             |
| `metadata`                | object                             |             |
| `createdAt`               | date-time                          |             |
| `updatedAt`               | date-time                          |             |

## Examples

### Subscribe to more event types

```http
PATCH /api/v1/webhook_endpoints/we_01m4tx5nj8emwbyf7y9vcf47z0
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "events": [
    "customer.created",
    "checkout.session.completed",
    "invoice.paid"
  ]
}
```

Response (`200`):

```json
{
  "id": "we_01m4tx5nj8emwbyf7y9vcf47z0",
  "object": "webhook_endpoint",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "url": "https://example.com/webhooks/ownrecord",
  "description": "Order fulfilment",
  "events": ["checkout.session.completed", "customer.created", "invoice.paid"],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "failingSince": null,
  "secretRotatedAt": null,
  "previousSecretExpiresAt": null,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}
```

### Enable an endpoint again after it was disabled for failing

```http
PATCH /api/v1/webhook_endpoints/we_01m4tx5nj8emwbyf7y9vcf47z0
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "enabled": true
}
```

Response (`200`):

```json
{
  "id": "we_01m4tx5nj8emwbyf7y9vcf47z0",
  "object": "webhook_endpoint",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "url": "https://example.com/webhooks/ownrecord",
  "description": "Order fulfilment",
  "events": ["customer.created", "checkout.session.completed"],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "failingSince": null,
  "secretRotatedAt": null,
  "previousSecretExpiresAt": null,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}
```

## Errors

| Code                                                                                                     | HTTP status | When                                                  | What to do                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)                   | 400         | No field to change was sent, or a field is malformed. | Fix the fields listed in `details.issues` and send the request again.                                                                                                        |
| [`webhook_url_not_allowed`](https://ownrecord.io/docs/reference/errors.md#webhook_url_not_allowed)       | 400         | The new URL isn't allowed.                            | Use a public https URL without a user name, password or #fragment, e.g. <https://example.com/webhooks>. In development, <http://localhost> works while the dev gate is open. |
| [`webhook_event_type_invalid`](https://ownrecord.io/docs/reference/errors.md#webhook_event_type_invalid) | 400         | An event type can't be delivered to brand endpoints.  | List event types from the event catalogue that are delivered to webhooks (docs: reference → events), or "\*" for all of them.                                                |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)                 | 404         | No endpoint with this ID is visible to the request.   | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                                                         |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)                     | 409         | The endpoint changed at the same time; retry.         | Fetch the object again and retry the change.                                                                                                                                 |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)                   | 403         | You can't manage this brand's webhooks.               | Ask an organization owner or admin for a role or scope that allows this action.                                                                                              |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).