Receiving webhooks

​

What gets delivered

1. Your user’s default webhook URL (configured in HG.Cash Settings alongside the webhook signing secret), or
2. A webhookUrl you pass per operation where the API or form allows it — for example creating a ledger transaction via the REST API (POST /api/v1/transactions) or a transaction request from the transfers flow when that field is available.

​

Topic and eventType

• Transaction requests (cash-out pipeline, type is always "request"): Transaction Request Status Updated — schema TransactionRequestStatusWebhook with a full example payload.
• Transaction request linked to ledger row (after Urbana associates the cash-out with the bank movement): Transaction request associated — same schema with required transactionId, topic TRANSACTION_REQUEST, and eventType transaction_associated. You may receive this in addition to a status update when the link is established.
• Ledger / account movements (money in or out of your HG.Cash accounts; type is your movement / transaction type name such as inbound or outbound): Account movement — schema AccountMovementWebhook with example payloads. When a fee snapshot was stored, the body includes optional feeBreakdown. See Fee breakdown. When a Brazil PIX movement stores an end-to-end id, the body includes optional endToEndId. See PIX end-to-end id.
• Hosted checkouts (event such as checkout.completed): Checkout events — schema WebhookCheckoutPayload. On checkout.completed, when a ledger transaction is linked, the payload includes a nested transaction object (same fields as Account movement, without topic or eventType). See Hosted checkout for flows by country.
• Claim status changes (topic CLAIM, eventType status_change): Claim status updated — schema ClaimStatusWebhook. Sent to your default webhook URL when a claim is updated by an admin or auto-reconciled by COELSA. The body matches the Get claim (GET /claims/{id}) response (without fileUrl) plus routing metadata, with an optional comment field. Webhooks are not sent on claim create or comment-only updates. See Claims for the full flow.

​

Fee breakdown

{
  "feeBreakdown": {
    "flatFee": { "amount": "15" },
    "collectedAmount": "135"
  }
}

​

PIX end-to-end id

• A PIX status update posts eventType status_change and the identifier is already stored.
• A later provider update stores the identifier for the first time and that update did not already notify you. HG.Cash then sends one TRANSACTION / status_change with the updated body.
• A dashboard resend posts eventType created from the stored movement, and the identifier is already saved.

{
  "topic": "TRANSACTION",
  "eventType": "status_change",
  "id": "040eac5b-a998-4879-9d8a-05fd2a08c625",
  "externalID": "bankizi-tx-01",
  "amount": "250.00",
  "currency": "BRL",
  "direction": "Inbound",
  "status": "done",
  "type": "inbound",
  "accountId": "843d9d8b-6db8-47a2-8c22-23b198e99c15",
  "date": "2026-05-02T21:40:00",
  "timezone": "America/Sao_Paulo",
  "endToEndId": "E60701190202505022140DY5DH1K8FL1"
}

​

Signing secret (X-HG-Webhook-Signature)

• Algorithm: HMAC-SHA256 over the UTF-8 bytes of the body string HG.Cash will send (JSON.stringify equivalent of the payload object).
• Header: X-HG-Webhook-Signature.
• Format: sha256=<hex> where <hex> is lowercase hex (64 chars).

1. Read the raw request body as delivered — do not re-serialize parsed JSON unless you replicate every key order/spacing HG.Cash used.
2. Compute hex = HMAC_SHA256(secret, rawBody_utf8) and compare securely to header value after stripping the optional sha256= prefix (case insensitive).
3. Reject mismatches (401/403 on your side is fine).

​

Retries

​

Operational expectations

• Respond with 2xx quickly so the delivery counts as successful; otherwise you may receive repeat POSTs until attempts are exhausted or one succeeds.
• Prefer idempotent handlers keyed by HG.Cash id and status transitions you care about — redeliveries or duplicate emits are possible alongside provider quirks.

​

Dashboard tools