Skip to main content

​
Qué se entrega

HG.Cash encola un POST asíncrono hacia:
  1. La URL de webhook predeterminada de tu usuario (configurada en Configuración de HG.Cash junto al secreto de firma del webhook), o
  2. Un webhookUrl que indiques por operación donde la API o el formulario lo permitan — por ejemplo al crear una transacción de libro vía API REST (POST /api/v1/transactions) o una solicitud de transacción desde transferencias cuando ese campo exista.
Los payloads tienen la misma forma sin importar la cola: Content-Type: application/json. Cada payload incluye topic y eventType en el nivel superior para enrutamiento. La mayoría de los cuerpos son un objeto JSON plano; checkout.completed puede incluir además un objeto transaction anidado con los datos del movimiento de libro (mismos campos que Movimiento de cuenta, sin topic ni eventType).

​
Topic y eventType

Las solicitudes de transacción usan siempre topic TRANSACTION_REQUEST. Cuando un cash-out se vincula al movimiento bancario, busque eventType transaction_associated (no un topic separado). La forma del payload y ejemplos están en la referencia API (pestaña Referencia API, sección Webhooks):
  • Solicitudes de transacción (pipeline cash-out; type es siempre "request"): Actualización de estado de solicitud de transacción — esquema TransactionRequestStatusWebhook con ejemplo completo.
  • Solicitud vinculada a la transacción de libro (después de asociar el cash-out con el movimiento bancario): Solicitud de transacción asociada — mismo esquema con transactionId obligatorio, topic TRANSACTION_REQUEST y eventType transaction_associated.
  • Movimientos de libro / cuenta (dinero entrante o saliente de tus cuentas HG.Cash; type es el nombre del tipo de movimiento como inbound u outbound): Movimiento de cuenta — esquema AccountMovementWebhook con ejemplos. Cuando se guardó un desglose de comisión, el cuerpo incluye feeBreakdown opcional. Ver Desglose de comisión. Cuando un movimiento PIX de Brasil guarda un identificador end-to-end, el cuerpo incluye endToEndId opcional. Ver Identificador end-to-end PIX.
  • Checkouts hospedados (event como checkout.completed): Eventos de checkout — esquema WebhookCheckoutPayload. En checkout.completed, cuando hay una transacción de libro vinculada, la carga incluye un objeto transaction anidado (mismos campos que Movimiento de cuenta, sin topic ni eventType). Ver Checkout hospedado.
  • Cambios de estado de reclamo (topic CLAIM, eventType status_change): Estado de reclamo actualizado — esquema ClaimStatusWebhook. Se envía a tu URL de webhook predeterminada cuando un administrador actualiza un reclamo o COELSA lo autoconcilia. El cuerpo coincide con la respuesta de Obtener reclamo (GET /claims/{id}, sin fileUrl) más los metadatos de enrutamiento, con un campo comment opcional. No se envían webhooks al crear un reclamo ni en actualizaciones que solo agregan un comentario. Ver Reclamos.
Solicitudes de transacción (type: "request") Los callbacks se envían cuando HG.Cash actualiza el estado de una solicitud o cuando una solicitud se cancela. Cuando una solicitud saliente se vincula a su transacción de libro, HG.Cash puede enviar Solicitud de transacción asociada con topic TRANSACTION_REQUEST, eventType transaction_associated y el transactionId del movimiento bancario. Es posible que no recibas webhook apenas se crea una solicitud si solo está PENDING; integra de forma defensiva ante orden y duplicados. Transacciones de libro Cuando una fila de transacción del libro se ingesta desde webhooks/API y aplica tu URL resuelta, HG.Cash puede notificar justo después de persistir; type es el nombre del tipo de negocio, no "request".

​
Desglose de comisión

Los webhooks de movimiento de cuenta (topic TRANSACTION, eventType created o status_change) incluyen feeBreakdown opcional cuando HG.Cash guardó un desglose de comisión en el movimiento. El campo se omite cuando no hay desglose. Las filas internas de comisión no envían un webhook. El objeto del webhook tiene dos campos. flatFee.amount es la comisión fija. collectedAmount es el porcentaje cobrado más esa comisión fija. Los webhooks no incluyen platformFee, transactionFee ni flatFee.source. En checkout.completed, el objeto transaction anidado usa los mismos campos, incluido feeBreakdown cuando el movimiento vinculado tiene un desglose.
En este ejemplo el monto del movimiento es 12.000. El porcentaje del cliente es 1% (120) más una comisión fija de 15, así que collectedAmount es 135. Esos montos porcentuales quedan en la respuesta de estado. No van en el webhook. GET /api/v1/{br,cl,co,bo}/transactions/{id}/status devuelve platformFee, transactionFee, flatFee (incluido source: account o platform) y collectedAmount cuando existe un desglose. El estado de Venezuela devuelve los mismos montos y omite flatFee.source. GET /transaction/{id}/status es el estado de una solicitud de transacción y no incluye feeBreakdown.

​
Identificador end-to-end PIX

Los webhooks de movimiento de cuenta (topic TRANSACTION, eventType created o status_change) incluyen endToEndId opcional cuando el movimiento guarda un identificador end-to-end de un PIX de Brasil. El valor es esa cadena almacenada, sin espacios al inicio ni al final. HG.Cash omite el campo cuando el identificador está ausente o vacío. El campo va en el nivel superior del JSON, junto a campos como id y status. Aplica a PIX de entrada y de salida. Lo recibes en estos casos:
  • Una actualización de estado PIX envía eventType status_change y el identificador ya está guardado.
  • Una actualización posterior del proveedor guarda el identificador por primera vez y esa actualización todavía no te notificó. HG.Cash envía entonces un TRANSACTION / status_change con el cuerpo actualizado.
  • Un reenvío desde el panel envía eventType created a partir del movimiento guardado, y el identificador ya está almacenado.
Un cambio de estado en la misma actualización incluye endToEndId una sola vez. Un identificador que ya estaba guardado no dispara otra entrega por sí solo. En checkout.completed, el objeto transaction anidado usa los mismos campos de movimiento, incluido endToEndId cuando el movimiento vinculado lo tiene.

​
Secreto de firma (X-HG-Webhook-Signature)

Si tu perfil HG.Cash tiene un secreto de firma de webhook configurado, HG.Cash firma el cuerpo JSON crudo exacto:
  • Algoritmo: HMAC-SHA256 sobre los bytes UTF-8 del string del cuerpo que HG.Cash enviará (equivalente a JSON.stringify del objeto payload).
  • Encabezado: X-HG-Webhook-Signature.
  • Formato: sha256=<hex> donde <hex> es hexadecimal en minúsculas (64 caracteres).
Pasos de verificación en tu servidor:
  1. Lee el cuerpo crudo tal como llega — no vuelvas a serializar JSON parseado salvo que repliques exactamente orden/espaciado que usó HG.Cash.
  2. Calcula hex = HMAC_SHA256(secret, rawBody_utf8) y compara de forma segura con el valor del encabezado tras quitar el prefijo opcional sha256= (sin distinguir mayúsculas/minúsculas).
  3. Rechaza discrepancias (401/403 en tu lado está bien).
Si no hay secreto configurado en HG.Cash, el encabezado X-HG-Webhook-Signature se omite por completo.

​
Reintentos

Las entregas fallidas (HTTP distinto de 2xx, errores de red o timeouts) se reintentan automáticamente con esta política: Cada intento tiene hasta 30 segundos de tiempo total de ejecución antes de que el trabajo de entrega se considere fallido para ese intento.

​
Expectativas operativas

  • Responde con 2xx rápido para que la entrega cuente como exitosa; si no, puedes recibir POST repetidos hasta agotar intentos o hasta que uno tenga éxito.
  • Prefiere manejadores idempotentes claveados por id de HG.Cash y transiciones de status que te importen — pueden existir reenvíos o emisiones duplicadas.

​
Herramientas en el panel

HG.Cash también registra cada intento de entrega en el panel (transacciones y transferencias → Webhooks) y puede deshabilitar tu webhook automáticamente si los fallos persisten. Consultá Historial de entregas y monitoreo de salud para logs, reintento manual y alertas por email.