> ## Documentation Index
> Fetch the complete documentation index at: https://docs.palomma.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
Palomma envia eventos de webhook cuando ocurre algo importante. Registra una URL con el equipo de Palomma y enviaremos un HTTP POST con un cuerpo JSON cada vez que ocurra un evento.
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 solicitud `POST` 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).
Tipo de evento: `invoice` o `settlement`.
Payload del evento. La estructura depende de `type` (ver abajo).
### Payloads de eventos
Se envia cuando una factura alcanza su estado final (`type: "invoice"`).
Identificador unico de la factura.
Referencia de la factura proporcionada por el comercio.
Uno de `ready`, `paid`, `cancelled` o `chargeback`.
Monto de la factura en COP.
Descripcion de la factura.
Identificador del contrato.
Fecha y hora de expiracion del link de pago (ISO 8601).
Numero de documento del cliente.
Nombre del cliente.
Fecha y hora de creacion de la factura (ISO 8601).
Cuando se pago la factura. Presente en facturas pagadas y con contracargo.
Metodo de pago utilizado. Presente en facturas pagadas y con contracargo.
Uno de `whatsapp`, `portal` o `link`. Presente en facturas pagadas y con contracargo.
Monto realmente pagado en COP. Presente en facturas pagadas y con contracargo.
Fecha esperada de liquidacion. Presente en facturas pagadas y con contracargo.
Ciclo esperado de liquidacion. Presente en facturas pagadas y con contracargo.
Identificador del pago. Presente en facturas pagadas y con contracargo.
URL de la pagina de pago de Palomma para esta factura.
Se envia cuando una liquidacion alcanza su estado final (`type: "settlement"`).
Fecha de la liquidacion.
Ciclo de la liquidacion.
Uno de `processing`, `paid`, `credited` o `error`.
Numero de facturas en la liquidacion.
Monto total recaudado (COP).
Comisiones aplicadas (COP).
Si las comisiones son pospago.
Ajustes aplicados (COP).
Si la liquidacion paso por el gateway.
Monto neto del pago (COP).
***
## Verificacion de firmas
Cada webhook incluye un header `X-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.
Siempre verifica la firma antes de procesar el evento.
Para verificar:
1. Lee el cuerpo crudo de la solicitud como string.
2. Calcula un HMAC-SHA256 de ese string usando tu `integrityKey`.
3. Compara el resultado con el header `X-Signature`. Si coinciden, la solicitud es autentica.
### Ejemplo (Node.js)
```javascript theme={null}
const crypto = require("crypto");
app.post("/webhooks", (req, res) => {
const signature = req.headers["x-signature"];
const rawBody = JSON.stringify(req.body);
const integrityKey = process.env.PALOMMA_INTEGRITY_KEY;
const expected = crypto
.createHmac("sha256", integrityKey)
.update(rawBody)
.digest("hex");
if (signature !== expected) {
return res.status(401).json({ error: "Firma invalida" });
}
// Confirmar recepcion inmediatamente, procesar despues
res.status(200).json({ ok: true });
// TODO: procesar req.body de forma asincrona
});
```
***
## Reintentos
Si una entrega falla, Palomma reintentara hasta **4 veces**. El tiempo de espera entre reintentos aumenta con cada intento:
| Intento | Espera aproximada |
| ------------- | ----------------- |
| 1er reintento | \~1 minuto |
| 2do reintento | \~5 minutos |
| 3er reintento | \~25 minutos |
| 4to reintento | \~2 horas |
Los tiempos exactos varian ligeramente para que los reintentos no lleguen todos al mismo instante a tu servidor.
## Manejo de duplicados
En los reintentos, el `webhookId` 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.
Asegurate de no procesar el mismo webhook mas de una vez.