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

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 deja de firmar de inmediato.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope webhooks:write. Formato: Bearer FD.<key_id>.<token>.

X-Instance-Slugstringheaderobligatorio

Request

Path params:

idinteger

Identificador del webhook.

Body (opcional):

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, la rotación mantiene el secreto anterior durante 24 horas.

Response

200 OKEl webhook, con los mismos campos que `GET /v1/webhooks/{id}`, más el secreto nuevo.

previous_secret_expires_atstring | nullobligatorio

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.

secretstringobligatorio

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 (pendiente de publicación).
• Rotar otra vez dentro de ese plazo descarta el secreto más antiguo.
• Si el secreto anterior quedó expuesto, conviene rotar con expire_previous: true.
• El secreto nuevo debe guardarse 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,
"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"
}