Regenerate webhook signing secret

POSThttps://api.veriko.mx/v1/webhooks/{id}/regenerate-secret

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

Rotates the secret used to sign this endpoint's delivery bodies. The new secret travels exactly once, in this response, and there is no way to read it again. The previous one is invalidated at once: there is no overlap window. A receiver validating signatures will stop validating the following deliveries until the new secret is configured on it, so the rotation is worth coordinating with that deployment. The previous one is invalidated immediately. Store it securely.

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

Request

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/webhooks/{id}/regenerate-secret' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200**`WebhookEndpoint` — New signing secret generated. Returned only in this response.
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**`POST /v1/webhooks/{id}/regenerate-secret`
Status	Class	Description	Body
200	`2xx`	New signing secret generated. Returned only in this response.	No body
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`
429	`4xx`	Rate limit exceeded	`ErrorResponse`

**Errors from `POST /v1/webhooks/{id}/regenerate-secret`**
Status	Code	Example
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`
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`).