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

Regenerar la firma secreta de un endpoint webhook

Audiencia: public
Autenticación: API key
Permiso: webhooks:update

Rota el secreto con el que se firman las entregas de un endpoint webhook. El secreto nuevo viaja una sola vez, en esta respuesta, y no hay forma de volver a consultarlo.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`id`*	path	`string (uuid)`	obligatorio	Identificador único del endpoint webhook (UUID v4). p. ej. `f47ac10b-58cc-4372-a567-0e02b2c3d479`

Petición

cURLPython•JavaScript•PHP•

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

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200**`WebhookEndpoint` — Nuevo secret generado. Solo se devuelve en esta respuesta.
Campo	Tipo	Descripción
`type`*	`string`	Tipo de recurso JSON:API. Siempre `webhook_endpoint`. p. ej. `webhook_endpoint`
`id`*	`string (uuid)`	Identificador único del endpoint webhook (UUID v4). p. ej. `a1b2c3d4-e5f6-7890-abcd-ef0123456789`
`attributes`*	`object`	Datos del endpoint webhook (URL receptora, eventos suscritos, estado y secreto).
`url`*	`string (uri)`	URL receptora del webhook. En producción se rechaza si no usa HTTPS, si resuelve a una dirección privada o si pasa de 2048 caracteres. p. ej. `https://example.com/webhooks/entregas`
`events`*	`array` (elementos: 1–10, elementos únicos)	Eventos a los que se suscribe el endpoint webhook. Entre 1 y 10.
`description`*	`string \| null`anulable	Etiqueta libre para distinguir el endpoint webhook de los demás. p. ej. `Alta de pagos en el ERP`
`status`*	`string`	Estado actual del webhook — `active`: Recibe entregas; `disabled`: Se desactivó manualmente; `auto_disabled`: Se desactivó automáticamente tras superar el umbral de fallos consecutivos. p. ej. `active`
`consecutive_failures`*	`integer`	Cantidad de fallos consecutivos. Se reinicia al primer éxito. p. ej. `0`
`last_delivery_at`*	`TimestampUTC \| null`	Fecha y hora de la última entrega exitosa, en ISO 8601 UTC. `null` cuando el endpoint aún no completó ninguna entrega.
`secret`	`string`	Clave compartida para verificar firmas. Solo presente en la respuesta de creación y de rotación del endpoint; se omite en cualquier otra respuesta. Se usa para validar las cabeceras `X-Webhook-Signature` y `X-Webhook-Signature-Timestamped` de cada entrega. p. ej. `a0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566778899aabbccddeeff`
`secret_hint`	`string`	Últimos 4 caracteres del secret, con el prefijo `...`. Presente en cualquier respuesta donde el `secret` completo está oculto. p. ej. `...4f2a`
`created_at`*	`string (date-time)`	Timestamp ISO 8601 en UTC con sufijo `Z` explícito; por ejemplo, `"2026-05-01T05:14:38Z"`. Los campos `_at`, `_end`, `_start` y `_date` adoptan esta forma. `meta.datetime` describe el mismo contrato en la respuesta. p. ej. `2026-05-01T05:14:38Z`
`updated_at`*	`string (date-time)`	Timestamp ISO 8601 en UTC con sufijo `Z` explícito; por ejemplo, `"2026-05-01T05:14:38Z"`. Los campos `_at`, `_end`, `_start` y `_date` adoptan esta forma. `meta.datetime` describe el mismo contrato en la respuesta. p. ej. `2026-05-01T05:14:38Z`

**Códigos de respuesta**`POST /v1/webhooks/{id}/regenerate-secret`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Nuevo secret generado. Solo se devuelve en esta respuesta.	`WebhookEndpoint`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	`not_found`: El endpoint no existe o no pertenece al usuario.	`ErrorResponse`
429	`4xx`	Límite de tasa excedido	`ErrorResponse`

**Errores de `POST /v1/webhooks/{id}/regenerate-secret`**
Código	Clave	Ejemplo
401	`unauthorized`	Credenciales de autenticación ausentes o inválidas. Envelope meta.request_id `c4d5e6f7a8b99b8a7f6e5d4c`
403	`permission_denied`	No tienes permiso para acceder a este recurso. Envelope meta.request_id `d5e6f7a8b9c00c9b8a7f6e5d`
429	`rate_limit_exceeded`	Límite de peticiones excedido. Inténtalo de nuevo en 45 segundos. Envelope meta.request_id `f7a8b9c0d1e22e1d0c9b8a7f` Cabeceras de respuesta `Retry-After`: integer — Segundos a esperar antes de reintentar. Coincide con la ventana de rate-limit del endpoint (típicamente 60s para listas, 1-5s para operaciones idempotentes en vuelo). `X-RateLimit-Limit`: integer — Límite de solicitudes configurado para este bucket. Se emite en cada 429 y, en la API autenticada, también en las respuestas correctas, donde es el tope por clave del plan de la cuenta. `X-RateLimit-Remaining`: integer — Solicitudes restantes en la ventana actual. Siempre 0 en el momento del 429; en una respuesta correcta de la API autenticada es lo que queda del tope por clave. `X-RateLimit-Reset`: integer — Unix epoch absoluto (segundos) en que se reinicia la ventana. Se emite en cada 429, junto con Retry-After, y en las respuestas correctas de la API autenticada. Puede existir sobreescritura por endpoint (p. ej. `rate_limited_login`).