Para habilitar webhooks, contacta al equipo de Palomma y proporcionanos la URL
donde deseas recibir los eventos.
Cuando notificamos
Solo enviamos webhooks en estado final. Cada factura y liquidacion genera una unica notificacion. No recibiras multiples webhooks mientras un recurso pasa por estados intermedios.Requisitos de respuesta
Tu endpoint debe devolver HTTP 200 en menos de 5 segundos. Si no recibimos respuesta a tiempo, la entrega se considera fallida y se reintentara. Recomendamos confirmar la recepcion inmediatamente y procesar el payload de forma asincrona.Estructura de la solicitud
Cada webhook es una solicitudPOST con un cuerpo JSON que contiene estos campos de nivel superior:
Identificador unico de esta notificacion. El mismo
webhookId se reutiliza en
los reintentos para que puedas deduplicar.Timestamp ISO 8601 del momento en que se realizo este intento de entrega (se actualiza en cada reintento).
Payloads de eventos
- Factura
- Liquidacion
Se envia cuando una factura alcanza su estado final (
type: "invoice").Verificacion de firmas
Cada webhook incluye un headerX-Signature para que puedas confirmar que la solicitud proviene de Palomma. La firma es un HMAC-SHA256 del cuerpo crudo de la solicitud, usando la integrityKey asignada a tu cuenta.
Para verificar:
- Lee el cuerpo crudo de la solicitud como string.
- Calcula un HMAC-SHA256 de ese string usando tu
integrityKey. - Compara el resultado con el header
X-Signature. Si coinciden, la solicitud es autentica.
Ejemplo (Node.js)
Reintentos
Si una entrega falla, Palomma reintentara hasta 4 veces. El tiempo de espera entre reintentos aumenta con cada intento:
Los tiempos exactos varian ligeramente para que los reintentos no lleguen todos al mismo instante a tu servidor.
Manejo de duplicados
En los reintentos, elwebhookId se mantiene igual pero el timestamp se actualiza. Almacena el webhookId despues de procesar un evento exitosamente. Si recibes el mismo webhookId de nuevo, ignoralo.
