Rotar el secreto de un webhook

POST/v1/webhooks/{id}/rotate-secret

Para desarrolladores

Descripción

Genera un secreto de firma nuevo para el webhook y lo devuelve. Es la única vez que se entrega. El secreto anterior sigue firmando junto al nuevo durante 24 horas, para que el endpoint pueda pasar al nuevo sin rechazar entregas. Con expire_previous: true, el secreto anterior deja de firmar de inmediato.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope webhooks:write. Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Request

Path params:

idintegerobligatorio

Identificador del webhook.

Body:

expire_previousboolean

true deja de firmar con el secreto anterior de inmediato, en lugar de mantenerlo 24 horas junto al nuevo. Default: false. Sin body, el secreto anterior se mantiene 24 horas.

Response

200 OKDevuelve el webhook con el secreto nuevo. Los campos son los que siguen.

previous_secret_expires_atstring | nullsiempre presente

Hasta cuándo firma el secreto anterior junto al nuevo. null si se rotó con expire_previous o si el webhook no tenía secreto.

secretstringsiempre presente

Secreto de firma nuevo. Solo se entrega en esta respuesta.

Errores

Código	Cuándo
404	El webhook no existe en la instancia (webhook_not_found).

Detalle completo en Errores genéricos.

Notas

• Durante las 24 horas de convivencia, cada entrega lleva dos firmas en webhook-signature, incluidos los reintentos y el evento de prueba: primero la del secreto nuevo y después la del anterior. Un receptor que acepta cualquiera de las dos, como las librerías de Standard Webhooks, no rechaza entregas durante el cambio. Ver Rotar el secreto.
• Rotar otra vez dentro de ese plazo descarta el secreto más antiguo.
• Si el secreto anterior quedó expuesto, rote con expire_previous: true.
• Guarde el secreto nuevo de inmediato: no se puede recuperar después.

Request

curl -X POST "https://$API_HOST/v1/webhooks/3/rotate-secret" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"id": 3,
"name": "CRM de ventas",
"url": "https://hooks.example.com/fidelizador",
"events": [
  "mail.sent",
  "mail.bounced"
],
"is_active": true,
"last_success_at": "2026-09-13T12:00:04Z",
"last_failure_at": null,
"last_status_code": 200,
"consecutive_failures": 0,
"failing_since": null,
"auto_paused_at": null,
"previous_secret_expires_at": "2026-09-15T10:10:00Z",
"created_at": "2026-09-10T15:30:00Z",
"updated_at": "2026-09-14T10:10:00Z",
"secret": "whsec_2xQ7kYp3uT0sWm9bVf6cLzRn8aHd1eJg"
}