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

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