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 ejemplo completo.
  • 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".

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