Saltar al contenido principal

Visión general

Los webhooks avisan a tus sistemas, casi en tiempo real, sobre hechos de negocio del Dunning: cobro pagado, acuerdo aceptado, disputa abierta, notificación entregada. En lugar de consultar la API cada cierto tiempo, registras un endpoint HTTPS y recibes cada evento como un POST JSON.

Webhooks

Cómo funciona​

  1. Ocurre un hecho (p. ej., pago identificado).
  2. El evento se persiste de forma inmutable — nada es fire-and-forget.
  3. Para cada endpoint suscrito, el sistema agenda una entrega con firma HMAC y la envía con reintento automático; cada intento queda registrado con request y response capturados.

Registrar un endpoint​

En la pantalla Webhooks del dashboard (o vía POST /api/v1/webhook-endpoints), informa:

  • URL: obligatoriamente https://. Las URLs que apuntan a redes internas se rechazan en el registro (INVALID_WEBHOOK_URL, protección anti-SSRF).
  • Descripción (opcional): para qué sirve ese endpoint.
  • Eventos: selecciona en el catálogo, agrupado por categoría, con "seleccionar todos" por grupo. Una lista vacía suscribe todos los eventos, incluso los que se creen en el futuro (el listado muestra el badge "Todos los eventos").
  • Autenticación (opcional): credenciales que el Dunning presenta a tu endpoint (Basic, Bearer o header custom), además de la firma HMAC que va siempre. Detalles en Seguridad.

Al crearlo, el secret del endpoint (prefijo whsec_) se muestra una única vez. Firma cada entrega y puede rotarse en cualquier momento.

Qué llega a tu endpoint​

Cada entrega es un POST con el payload:

{
  "event": "charge.paid",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "3f8a...",
  "data": { "id": "...", "status": "paid", "...": "el recurso serializado" }
}

Y los headers:

Content-Type: application/json
User-Agent: Kobana-Dunning-Webhooks/1.0
X-Webhook-Event: charge.paid
X-Webhook-Event-Id: 3d1f0c9a-…      (UUID del evento — el mismo en todos los reintentos)
X-Webhook-Delivery-Id: 9b2e4a10-…   (UUID de la entrega — único por evento × endpoint)
X-Webhook-Attempt: 1                (número del intento)
X-Webhook-Timestamp: 2026-07-23T12:00:00.000Z
X-Webhook-Signature: t=<unix>,v1=<hmac-sha256 de "t.body" con el secret>

Responde 2xx para confirmar la recepción. Cualquier otra respuesta (incluidos los redirects, que no se siguen) cuenta como fallo y entra en el ciclo de reintentos.

Probar el endpoint​

Después de registrarlo, dispara un evento de prueba con POST /api/v1/webhook-endpoints/{id}/test: un evento webhook.test recorre el pipeline real (cola, firma, captura, reintento) hasta tu consumidor — sin esperar a que ocurra un evento de negocio.

Buenas prácticas​

  • Responde rápido y procesa después: encola el payload y devuelve 200 de inmediato (el timeout de entrega es de 10 segundos).
  • Trátalo como al-menos-una-vez: los reintentos pueden entregar el mismo evento más de una vez; deduplica por el X-Webhook-Event-Id (estable entre intentos).
  • Verifica la firma siempre, incluida la ventana de tolerancia del timestamp (cómo hacerlo).
  • Monitorea la pantalla de entregas: los fallos y agotamientos quedan visibles por endpoint, con reenvío manual.

En esta sección​

  • Eventos — el catálogo completo con payload de ejemplo, recurso por recurso.
  • Seguridad — firma HMAC, verificación y autenticación del request.
  • Entregas y reintentos — captura, backoff, DLQ y reenvío manual.