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

Regenerate webhook signing 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.

Parameters
Parameter	In	Type	Required	Description
`id`*	path	`string (uuid)`	required	Unique identifier of the webhook endpoint (UUID v4). 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`	JSON:API resource type. Always `webhook_endpoint`. e.g. `webhook_endpoint`
`id`*	`string (uuid)`	Unique identifier of the webhook endpoint (UUID v4). e.g. `a1b2c3d4-e5f6-7890-abcd-ef0123456789`
`attributes`*	`object`	Webhook endpoint data (receiver URL, subscribed events, status, and secret).
`url`*	`string (uri)`	URL that receives the webhook. In production it is rejected if it does not use HTTPS, if it resolves to a private address, or if it is longer than 2048 characters. e.g. `https://example.com/webhooks/entregas`
`events`*	`array` (items: 1–10, unique items)	Events the endpoint subscribes to, from 1 to 10.
`description`*	`string \| null`nullable	Free-form label to tell this endpoint apart from the others. e.g. `Alta de pagos en el ERP`
`status`*	`string`	`active` receives deliveries. `disabled` was manually turned off. `auto_disabled` was turned off by the platform after exceeding the consecutive-failure threshold. e.g. `active`
`consecutive_failures`*	`integer`	Number of consecutive failures. Resets on the first success. e.g. `0`
`last_delivery_at`*	`TimestampUTC \| null`	Date and time of the last successful delivery, in ISO 8601 UTC. `null` when the endpoint has not completed a delivery yet.
`secret`	`string`	Shared secret for signature verification. Only present in the create and rotate-secret responses; omitted from every other response. It is used to validate the `X-Webhook-Signature` and `X-Webhook-Signature-Timestamped` headers on each delivery. e.g. `a0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566778899aabbccddeeff`
`secret_hint`	`string`	Last 4 characters 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 an explicit `Z` suffix; for example, `"2026-05-01T05:14:38Z"`. The `_at`, `_end`, `_start`, and `_date` fields follow this format. `meta.datetime` describes the same contract in the response. e.g. `2026-05-01T05:14:38Z`
`updated_at`*	`string (date-time)`	ISO 8601 timestamp in UTC with an explicit `Z` suffix; for example, `"2026-05-01T05:14:38Z"`. The `_at`, `_end`, `_start`, and `_date` fields follow this format. `meta.datetime` describes the same contract in the response. 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.	`WebhookEndpoint`
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 `c4d5e6f7a8b99b8a7f6e5d4c`
403	`permission_denied`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c00c9b8a7f6e5d`
429	`rate_limit_exceeded`	Rate limit exceeded. Try again in 45 seconds. Envelope meta.request_id `f7a8b9c0d1e22e1d0c9b8a7f` 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. It is emitted on every 429 and, on the authenticated API, also on successful responses, where it is the per-key cap of the account plan. `X-RateLimit-Remaining`: integer — Requests remaining in the current window. Always 0 at the moment of the 429; on a successful response of the authenticated API it is what is left of the per-key cap. `X-RateLimit-Reset`: integer — Absolute Unix epoch (seconds) when the window resets. Emitted on every 429, alongside Retry-After, and on successful responses of the authenticated API. Per-endpoint overrides exist (e.g. `rate_limited_login`).