Regenerar el secret de firma del webhook

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

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

Rota el secreto con el que se firma el cuerpo de las entregas de este endpoint. El secreto nuevo viaja una sola vez, en esta respuesta, y no hay forma de volver a consultarlo. El anterior queda invalidado en el acto: no hay periodo de solapamiento. Un receptor que valide firmas dejará de validar las entregas siguientes hasta que se le configure el secreto nuevo, así que la rotación conviene coordinarla con ese despliegue.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`id`*	path	`string (uuid)`	obligatorio	UUID del endpoint de webhook. 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 del recurso, fijo para esta operación. Forma parte de la identidad del recurso en la envoltura JSON:API. Siempre `webhook_endpoint`. p. ej. `webhook_endpoint`
`id`*	`string (uuid)`	Identificador del endpoint. p. ej. `a1b2c3d4-e5f6-7890-abcd-ef0123456789`
`attributes`*	`object`	Atributos canónicos del endpoint de webhook (URL receptora, eventos suscritos, estado y secreto).
`url`	`string (uri)`	URL HTTPS receptora. En producción se rechaza HTTP, URLs que resuelven a IPs privadas (SSRF), y URLs `>2048` caracteres. p. ej. `https://example.com/webhooks/entregas`
`events`	`array`	Lista de eventos suscritos. Máximo 10.
`description`	`string \| null`anulable	Etiqueta libre del endpoint. p. ej. `Alta de pagos en el ERP`
`status`	`string`	`active` recibe entregas. `disabled` fue apagado manualmente. `auto_disabled` fue desactivado por la plataforma tras superar `webhooks.auto_disable_threshold` fallos consecutivos. p. ej. `active`
`consecutive_failures`	`integer`	Contador de fallos consecutivos. Se resetea en éxito. p. ej. `0`
`last_delivery_at`	`TimestampUTC \| null`	Marca de tiempo UTC del último intento de entrega (cualquier status). `null` cuando el endpoint aún no recibió ningún delivery.
`secret`	`string`	Clave compartida para verificar firmas. Solo presente en la respuesta de creación y regeneración del endpoint; se omite en cualquier otra respuesta. p. ej. `whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`
`secret_hint`	`string`	Últimos 4 caracteres del secret, prefijados con `...`. Presente en cualquier respuesta donde `secret` está oculto. p. ej. `...4f2a`
`created_at`	`string (date-time)`	Timestamp ISO 8601 en UTC con sufijo `Z` explícito. Ejemplo: `"2026-05-01T05:14:38Z"`. Cada campo `_at`, `_end`, `_start`, `_date` de la API usa esta forma. El descriptor compañero en `meta.datetime` permite afirmar el contrato en tiempo de ejecución sin volver a leer este spec. El `new Date(value)` nativo del navegador, el `datetime.fromisoformat` (≥3.11) de Python y el `time.Parse(time.RFC3339)` de Go parsean este formato directamente. p. ej. `2026-05-01T05:14:38Z`
`updated_at`	`string (date-time)`	Timestamp ISO 8601 en UTC con sufijo `Z` explícito. Ejemplo: `"2026-05-01T05:14:38Z"`. Cada campo `_at`, `_end`, `_start`, `_date` de la API usa esta forma. El descriptor compañero en `meta.datetime` permite afirmar el contrato en tiempo de ejecución sin volver a leer este spec. El `new Date(value)` nativo del navegador, el `datetime.fromisoformat` (≥3.11) de Python y el `time.Parse(time.RFC3339)` de Go parsean este formato directamente. 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.	Sin cuerpo
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 `c4d5e6f7a8b9`
403	`forbidden`	No tienes permiso para acceder a este recurso. Envelope meta.request_id `d5e6f7a8b9c0`
429	`rate_limit_exceeded`	Límite de peticiones excedido. Inténtalo de nuevo en 45 segundos. Envelope meta.request_id `f7a8b9c0d1e2` 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 (emitido sólo en 429). `X-RateLimit-Remaining`: integer — Solicitudes restantes en la ventana actual — siempre 0 en el momento del 429 (emitido sólo en 429). `X-RateLimit-Reset`: integer — Unix epoch absoluto (segundos) en que se reinicia la ventana. Emitido sólo en 429, junto con Retry-After. Puede existir sobreescritura por endpoint (p. ej. `rate_limited_login`).