Skip to main content

​
O que é entregue

A HG.Cash enfileira um POST assíncrono para:
  1. A URL de webhook padrão do usuário (configurada em Configurações da HG.Cash junto com o segredo de assinatura do webhook), ou
  2. Um webhookUrl informado por operação onde a API ou o formulário permitirem — por exemplo ao criar uma transação de ledger pela API REST (POST /api/v1/transactions) ou uma solicitação de transação nos fluxos de transferência quando o campo existir.
Os payloads têm o mesmo formato independentemente da fila: Content-Type: application/json. Cada payload inclui topic e eventType no nível superior para roteamento. A maioria dos corpos é um objeto JSON plano; checkout.completed pode incluir também um objeto transaction aninhado com os dados da movimentação no ledger (mesmos campos de Movimentação de conta, sem topic nem eventType).

​
Topic e eventType

Solicitações de transação usam sempre topic TRANSACTION_REQUEST. Quando um cash-out é vinculado ao movimento bancário, procure eventType transaction_associated (não um topic separado). O formato do payload e exemplos estão na referência da API (aba Referência da API, seção Webhooks):
  • Solicitações de transação (pipeline cash-out; type é sempre "request"): Atualização de status da solicitação de transação — schema TransactionRequestStatusWebhook com exemplo completo.
  • Solicitação vinculada à transação de ledger (após associar o cash-out ao movimento bancário): Solicitação de transação associada — mesmo schema com transactionId obrigatório, topic TRANSACTION_REQUEST e eventType transaction_associated.
  • Movimentações de conta / ledger (dinheiro entrando ou saindo das contas HG.Cash; type é o nome do tipo de movimento como inbound ou outbound): Movimento de conta — schema AccountMovementWebhook com exemplos. Quando um detalhamento de taxa foi salvo, o corpo inclui feeBreakdown opcional. Veja Detalhamento da taxa. Quando uma movimentação PIX do Brasil armazena um identificador end-to-end, o corpo inclui endToEndId opcional. Veja Identificador end-to-end PIX.
  • Checkouts hospedados (event como checkout.completed): Eventos de checkout — schema WebhookCheckoutPayload. Em checkout.completed, quando há uma transação de ledger vinculada, o payload inclui um objeto transaction aninhado (mesmos campos de Movimentação de conta, sem topic nem eventType). Veja Checkout hospedado.
  • Mudanças de status de reclamação (topic CLAIM, eventType status_change): Status da reclamação atualizado — schema ClaimStatusWebhook. Enviado para a sua URL de webhook padrão quando um administrador atualiza uma reclamação ou a COELSA a autoconcilia. O corpo corresponde à resposta de Obter reclamação (GET /claims/{id}, sem fileUrl) mais os metadados de roteamento, com um campo comment opcional. Webhooks não são enviados na criação da reclamação nem em atualizações que apenas adicionam um comentário. Veja Reclamações.
Solicitações de transação (type: "request") Callbacks são enviados quando a HG.Cash atualiza o status de uma solicitação ou quando uma solicitação é cancelada. Quando uma solicitação de saída é vinculada à transação de ledger, a HG.Cash pode enviar Solicitação de transação associada com topic TRANSACTION_REQUEST, eventType transaction_associated e o transactionId do movimento bancário. Você pode não receber webhook assim que uma solicitação é criada enquanto estiver apenas PENDING; integre de forma defensiva contra ordem e duplicatas. Transações de ledger Quando uma linha de transação do ledger é persistida a partir de webhooks/API e sua URL resolvida se aplica, a HG.Cash pode notificar logo após persistir; type é o nome do tipo de negócio, não "request".

​
Detalhamento da taxa

Webhooks de movimentação de conta (topic TRANSACTION, eventType created ou status_change) incluem feeBreakdown opcional quando a HG.Cash salvou um detalhamento de taxa na movimentação. O campo é omitido quando não há detalhamento. Linhas internas de taxa não enviam webhook. O objeto do webhook tem dois campos. flatFee.amount é a taxa fixa. collectedAmount é o percentual cobrado mais essa taxa fixa. Webhooks não incluem platformFee, transactionFee nem flatFee.source. Em checkout.completed, o objeto transaction aninhado usa os mesmos campos, inclusive feeBreakdown quando a movimentação vinculada tem um detalhamento.
Neste exemplo o valor da movimentação é 12.000. O percentual do cliente é 1% (120) mais uma taxa fixa de 15, então collectedAmount é 135. Esses valores percentuais ficam na resposta de status. Eles não vão no webhook. GET /api/v1/{br,cl,co,bo}/transactions/{id}/status devolve platformFee, transactionFee, flatFee (incluindo source: account ou platform) e collectedAmount quando existe um detalhamento. O status da Venezuela devolve os mesmos valores e omite flatFee.source. GET /transaction/{id}/status é o status de uma solicitação de transação e não inclui feeBreakdown.

​
Identificador end-to-end PIX

Webhooks de movimentação de conta (topic TRANSACTION, eventType created ou status_change) incluem endToEndId opcional quando a movimentação armazena um identificador end-to-end de um PIX do Brasil. O valor é essa string armazenada, sem espaços no início ou no fim. A HG.Cash omite o campo quando o identificador está ausente ou vazio. O campo fica no nível superior do JSON, junto de campos como id e status. Vale para PIX de entrada e de saída. Você recebe o campo nestes casos:
  • Uma atualização de status PIX envia eventType status_change e o identificador já está armazenado.
  • Uma atualização posterior do provedor grava o identificador pela primeira vez e essa atualização ainda não notificou você. A HG.Cash envia então um TRANSACTION / status_change com o corpo atualizado.
  • Um reenvio pelo painel envia eventType created a partir da movimentação armazenada, e o identificador já está salvo.
Uma mudança de status na mesma atualização inclui endToEndId uma única vez. Um identificador que já estava armazenado não gera outra entrega por si só. Em checkout.completed, o objeto transaction aninhado usa os mesmos campos de movimentação, inclusive endToEndId quando a movimentação vinculada tem um.

​
Segredo de assinatura (X-HG-Webhook-Signature)

Se o perfil HG.Cash tiver um segredo de assinatura de webhook configurado, a HG.Cash assina o corpo JSON bruto exato:
  • Algoritmo: HMAC-SHA256 sobre os bytes UTF-8 da string do corpo que a HG.Cash enviará (equivalente a JSON.stringify do objeto payload).
  • Cabeçalho: X-HG-Webhook-Signature.
  • Formato: sha256=<hex> onde <hex> é hexadecimal minúsculo (64 caracteres).
Passos de verificação no seu servidor:
  1. Leia o corpo bruto como recebido — não re-serialize JSON parseado salvo que replique cada ordem/espaçamento que a HG.Cash usou.
  2. Calcule hex = HMAC_SHA256(secret, rawBody_utf8) e compare com segurança ao valor do cabeçalho após remover o prefixo opcional sha256= (sem diferenciar maiúsculas/minúsculas).
  3. Rejeite divergências (401/403 no seu lado é aceitável).
Se não houver segredo configurado na HG.Cash, o cabeçalho X-HG-Webhook-Signature é omitido por completo.

​
Tentativas novamente

Entregas com falha (HTTP diferente de 2xx, erros de rede ou timeouts) são repetidas automaticamente com esta política: Cada tentativa tem até 30 segundos de tempo total de execução antes da entrega ser tratada como falha naquela tentativa.

​
Expectativas operacionais

  • Responda com 2xx rapidamente para que a entrega conte como sucesso; caso contrário você pode receber POST repetidos até esgotar tentativas ou até uma tentativa bem-sucedida.
  • Prefira handlers idempotentes chaveados pelo id da HG.Cash e transições de status relevantes — reenvios ou emissões duplicadas são possíveis.

​
Ferramentas no painel

A HG.Cash também registra cada tentativa de entrega no painel (transações e transferências → Webhooks) e pode desabilitar seu webhook automaticamente se as falhas persistirem. Veja Histórico de entregas e monitoramento de saúde para logs, retentativa manual e alertas por e-mail.