Update a webhook endpoint

PUThttps://api.veriko.mx/v1/webhooks/{id}

Audience: public
Auth: API key
Permission: webhooks:update

Updates the receiving address, the subscribed events, or the status of an already registered endpoint. Only what arrives in the body changes: an absent field stays as it was, and a body with no editable field responds 422 no_valid_fields. The signing secret does not change here. Changing the address leaves the same secret on the new endpoint, so a receiver that already validated signatures keeps validating them. To rotate it there is POST /v1/webhooks/{id}/regenerate-secret. Setting the status to disabled stops deliveries without losing the history; that is the move while a downed receiver is being fixed, rather than deleting the endpoint and creating it again.

Parameters
Parameter	In	Type	Required	Description
`id`*	path	`string (uuid)`	required	UUID of the webhook endpoint. e.g. `f47ac10b-58cc-4372-a567-0e02b2c3d479`

Parameters
Parameter	Type	Required	Description
`url`	string (uri) (?–2048)	optional	HTTPS destination URL. Replaces the previous URL when provided. e.g. `https://example.com/webhooks/entregas`
`events`	array<string> (items: 1–10)	optional	Webhook event subscription. Replaces the previous list; max 10 events.
`description`	string \| nullnullable (?–255)	optional	Free-form webhook label (`null` to clear it). e.g. `Alta de pagos en el ERP`
`status`	string (enum)	optional	Changes the webhook state (`active` or `disabled`). e.g. `active`

Request

cURLPython•JavaScript•PHP•

curl -X PUT 'https://api.veriko.mx/v1/webhooks/{id}' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://webhook.example.com/platform",
    "events": [
      "validation.completed"
    ],
    "status": "active"
  }'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200**`WebhookEndpoint` — Endpoint updated.
Field	Type	Description
`type`*	`string`	Resource type, fixed for this operation. Part of the resource identity in the JSON:API envelope. Always `webhook_endpoint`. e.g. `webhook_endpoint`
`id`*	`string (uuid)`	Endpoint identifier. e.g. `a1b2c3d4-e5f6-7890-abcd-ef0123456789`
`attributes`*	`object`	Canonical webhook endpoint attributes (receiver URL, subscribed events, status, and secret).
`url`	`string (uri)`	HTTPS receiver URL. Production rejects plain HTTP, URLs resolving to private IPs (SSRF), and URLs `>2048` chars. e.g. `https://example.com/webhooks/entregas`
`events`	`array`	List of subscribed events. Maximum 10.
`description`	`string \| null`nullable	Free-form endpoint label. e.g. `Alta de pagos en el ERP`
`status`	`string`	`active` receives deliveries. `disabled` was manually paused. `auto_disabled` was disabled by the platform after exceeding `webhooks.auto_disable_threshold` consecutive failures. e.g. `active`
`consecutive_failures`	`integer`	Consecutive failures counter. Resets on a success. e.g. `0`
`last_delivery_at`	`TimestampUTC \| null`	UTC timestamp of the last delivery attempt (any status). `null` when the endpoint hasn't received any delivery yet.
`secret`	`string`	Shared secret for signature verification. Only present in the create and rotate-secret responses; omitted from every other response. e.g. `whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`
`secret_hint`	`string`	Last 4 chars of the secret prefixed with `...`. Present on any response where the full `secret` is hidden. e.g. `...4f2a`
`created_at`	`string (date-time)`	ISO 8601 timestamp in UTC with explicit `Z` suffix. Example: `"2026-05-01T05:14:38Z"`. Every datetime field uses this shape. The descriptor at `meta.datetime` makes the contract runtime-assertable. e.g. `2026-05-01T05:14:38Z`
`updated_at`	`string (date-time)`	ISO 8601 timestamp in UTC with explicit `Z` suffix. Example: `"2026-05-01T05:14:38Z"`. Every datetime field uses this shape. The descriptor at `meta.datetime` makes the contract runtime-assertable. e.g. `2026-05-01T05:14:38Z`

**Response status codes**`PUT /v1/webhooks/{id}`
Status	Class	Description	Body
200	`2xx`	Endpoint updated.	No body
400	`4xx`	The request body is empty or is not valid JSON.	`ErrorResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Insufficient permissions.	`ErrorResponse`
404	`4xx`	`not_found` — endpoint does not exist or does not belong to the user.	`ErrorResponse`
413	`4xx`	The request body exceeds the maximum accepted size (`body_too_large`).	`ErrorResponse`
422	`4xx`	Invalid data. Possible codes: `webhook_url_empty`, `webhook_url_too_long`, `webhook_url_invalid_format`, `webhook_url_not_https`, `webhook_events_required`, `webhook_events_too_many`, `webhook_event_invalid`, `webhook_status_invalid`, `no_valid_fields`.	`ErrorResponse`
429	`4xx`	Rate limit exceeded	`ErrorResponse`

**Errors from `PUT /v1/webhooks/{id}`**
Status	Code	Example
400	`body_empty`	The request body is empty. Envelope meta.request_id `c4d5e6f7a8b9`
400	`invalid_json`	The body is not valid JSON. Envelope meta.request_id `d5e6f7a8b9c0`
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`
413	`body_too_large`	The request body is too large. Envelope meta.request_id `1a2b3c4d5e6f`
429	`rate_limit_exceeded`	Rate limit exceeded. Try again in 45 seconds. Envelope meta.request_id `f7a8b9c0d1e2` Response headers `Retry-After`: integer — Seconds to wait before retrying. Matches the endpoint's rate-limit window (typically 60s for list endpoints, 1-5s for in-flight idempotent operations). `X-RateLimit-Limit`: integer — Configured request cap for this bucket (emitted only on 429). `X-RateLimit-Remaining`: integer — Requests remaining in the current window — always 0 at the moment of the 429 (emitted only on 429). `X-RateLimit-Reset`: integer — Absolute Unix epoch (seconds) when the window resets. Emitted only on 429, alongside Retry-After. Per-endpoint overrides exist (e.g. `rate_limited_login`).