Webhooks outbound

Envelope y headers

• X-Gallo-Signature — HMAC-SHA256 en hex de ${timestamp}.${body}
• X-Gallo-Timestamp — Unix time en segundos
• X-Gallo-Event-Id — idempotencia del receptor
• X-Gallo-Event-Type — tipo de evento

{
  "eventId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "type": "transfer.confirmed",
  "version": "1",
  "occurredAt": "2026-07-30T12:00:00.000Z",
  "tenantId": "3f6d9c1e-8b2a-4a1f-9c3e-6b7a1d2e5f40",
  "data": { }
}

Secret: whsec_….

Verificar la firma (Node.js)

const crypto = require('crypto');

function verify(req, secret) {
  const ts = req.headers['x-gallo-timestamp'];
  const sig = req.headers['x-gallo-signature'];
  const body = req.rawBody; // body crudo, sin re-serializar
  const expected = crypto
    .createHmac('sha256', secret) // whsec_...
    .update(ts + '.' + body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(sig),
  );
}

• Firmá sobre el body crudo (no re-serialices JSON).
• Rechazá timestamps viejos (p. ej. > 5 min) para evitar replay.

Payloads de ejemplo

account.created

{
  "eventId": "…",
  "type": "account.created",
  "version": "1",
  "occurredAt": "2026-08-07T12:00:00.000Z",
  "tenantId": "…",
  "data": {
    "cvu": "0000003100000000000147",
    "cuit": "20370994049",
    "titular": "JUAN PEREZ",
    "tipoPersona": "F"
  }
}

account.credited (cash-in)

{
  "type": "account.credited",
  "data": {
    "cvu": "0000003100000000000147",
    "importe": "2500.00",
    "idCoelsa": "G1LMP68NKVYE3XD2R7OEV4",
    "externalId": "aviso-credito-…"
  }
}

transfer.confirmed

{
  "type": "transfer.confirmed",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "idTrxCliente": "1024",
    "idTrxCoelsa": "G1LMP68NKVYE3XD2R7OEV4",
    "cvuDebito": "0000208200000000000147",
    "cbuCredito": "0000208200000000000291",
    "importe": "1500.50",
    "status": "confirmed",
    "estadoCodigo": "00",
    "isInternal": false
  }
}

transfer.failed

{
  "type": "transfer.failed",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "failed",
    "errorCoelsa": "Error del banco (400): …",
    "estadoCodigo": "41",
    "estadoDescripcion": "ERROR"
  }
}

Tipos de evento

Cuentas

account.created · account.alias.updated · account.suspended · account.closed · account.credited

Transferencias

transfer.created · transfer.sent · transfer.confirmed · transfer.failed · transfer.reversed

DEBIN

debin.adhesion.* (created, updated, confirmed, rejected, cancelled) · debin.programado.* (created, pending, credited, finalized, chargeback) · debin.spot.* (created, deleted) · debin.pull.* (created, chargeback) · debin.debit.confirmed · debin.pending · debin.credited. Ver guía DEBIN.

Pago QR

qr.created · qr.pending · qr.debit.confirmed · qr.debit.rejected · qr.finalized · qr.credited · qr.chargeback · qr.cashout.created · qr.cashout.pending · qr.cashout.confirmed · qr.commerce.created. Ver guía Pago QR.

Promociones

promo.applied · promo.skipped · promo.reversed. Ver guía de promociones.

Retries

Respondé 2xx rápido. Ante error o timeout reintentamos con backoff exponencial hasta agotar los intentos. Deduplicá con X-Gallo-Event-Id.

Hub developers · Transferencias.