Update a webhook endpoint · Ownrecord docs

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

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`	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`	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`	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`	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`	409	The endpoint changed at the same time; retry.	Fetch the object again and retry the change.
`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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Subscribe to more event types#

Enable an endpoint again after it was disabled for failing#

Errors#