Saltar al contenido principal
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:
​
webhookId
string
Identificador unico de esta notificacion. El mismo webhookId se reutiliza en los reintentos para que puedas deduplicar.
​
timestamp
string
Timestamp ISO 8601 del momento en que se realizo este intento de entrega (se actualiza en cada reintento).
​
type
string
Tipo de evento: invoice o settlement.
​
data
object
Payload del evento. La estructura depende de type (ver abajo).

​
Payloads de eventos

Se envia cuando una factura alcanza su estado final (type: "invoice").
​
id
string
Identificador unico de la factura.
​
reference
string
Referencia de la factura proporcionada por el comercio.
​
status
string
Uno de ready, paid, cancelled o chargeback.
​
amount
number
Monto de la factura en COP.
​
description
string
Descripcion de la factura.
​
contract
string
Identificador del contrato.
​
expirationDate
string
Fecha y hora de expiracion del link de pago (ISO 8601).
​
customerDocumentNumber
string
Numero de documento del cliente.
​
customerName
string
Nombre del cliente.
​
createdAt
string
Fecha y hora de creacion de la factura (ISO 8601).
​
paymentDate
string
Cuando se pago la factura. Presente en facturas pagadas y con contracargo.
​
paymentMethod
string
Metodo de pago utilizado. Presente en facturas pagadas y con contracargo.
​
paymentSource
string
Uno de whatsapp, portal o link. Presente en facturas pagadas y con contracargo.
​
paymentAmount
number
Monto realmente pagado en COP. Presente en facturas pagadas y con contracargo.
​
settlementDate
string
Fecha esperada de liquidacion. Presente en facturas pagadas y con contracargo.
​
settlementTime
string
Ciclo esperado de liquidacion. Presente en facturas pagadas y con contracargo.
​
paymentId
string
Identificador del pago. Presente en facturas pagadas y con contracargo.
​
paymentUrl
string
URL de la pagina de pago de Palomma para esta factura.

​
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)

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:
IntentoEspera 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.