Skip to Content
DocsEnterprise CapabilitiesUse CasesAnalytics, Subscriptions & WebhooksTransaction Webhooks & Notifications

Transaction Webhooks

Push notification on payment status with HMAC-SHA256 signed payloads and a timestamp-based replay window — so your backend can react to settled payments instead of polling.

Who this is for

PersonaTypical inbound
Merchant with automated fulfilment”Notify our backend when a customer payment settles, so we can release the order without polling.”
SaaS billing backend”Trigger subscription activation the moment the on-chain payment confirms.”
Marketplace operator”Settle a buyer payment to a seller as soon as it arrives, with cryptographic proof the callback came from you.”
Treasury or operations team”We want a callback we can audit, not a job that polls a status endpoint every minute.”

Not a fit if you need a fully self-service webhook subscription dashboard with per-event-type filtering today (per-intent callback URLs are how it works today; an organisation-wide subscription model is on the roadmap), webhooks for events outside the payment platform today (custodial-transfer notifications are on the near-term roadmap), or callbacks with sub-second guaranteed delivery (delivery is best-effort within a defined window).

What you can ship today

CapabilityWhat it includes
Payment-intent callbacksA callback URL set at payment-intent creation time. The platform POSTs a JSON payload on every status transition (pending, success, expired, refunded, cancelled).
HMAC-SHA256 signingEvery payment-intent callback payload includes an HMAC-SHA256 signature in a signature field on the JSON body, computed against a canonical serialisation of the payload using your shared secret.
Timestamp-based replay protectionEvery payload includes a timestamp field; receivers reject deliveries with a timestamp outside a five-minute validity window.
Callback delivery logA queryable log of recent callback attempts, with the request body and response status, accessible via your operator surface.
Manual test deliveryA test endpoint to send a synthetic callback to your URL during integration.

How it works

1. Your backend creates a payment intent and supplies a callback_url.

2. The customer pays on-chain. KryptoGO's chain watchers detect the
   transaction and advance the payment-intent state machine.

3. On every status transition, the backend POSTs a JSON payload to
   your callback_url. The payload includes:
     - the payment intent id, status, amounts, and on-chain tx hash
     - a timestamp field
     - a signature field — HMAC-SHA256 of the canonical payload body,
       computed with your shared secret

4. Your receiver:
     - verifies the signature against the canonical payload
     - checks the timestamp is within the 5-minute validity window
     - treats the delivery as idempotent (the same status change can
       arrive more than once on retry paths)
     - returns 200 to acknowledge

5. If you miss a delivery (your endpoint was down, the network failed,
   or the signature check rejected it), you can reconcile by querying
   the payment intent directly. The intent is the source of truth.

The signature lives in the JSON body rather than an HTTP header. That keeps the payload self-contained — the same canonical bytes that the signature covers are the bytes you receive. Verification logic is identical across HTTP transport variants (proxies, load balancers, log aggregators that strip headers).

Sample callback payload

{
  "payment_intent_id": "0h39QkYfZps7AUD1xQsj3MDFVLIMaGoV",
  "status": "success",
  "payment_chain_id": "arb",
  "symbol": "USDT",
  "fiat_amount": "300.0",
  "fiat_currency": "TWD",
  "crypto_amount": "2.53",
  "received_crypto_amount": "2.53",
  "payment_tx_hash": "0x1234...cdef",
  "order_data": { "order_id": "uid_12345", "item_id": "100" },
  "callback_url": "https://example.com/callback",
  "timestamp": 1715462400,
  "signature": "<HMAC-SHA256 of the canonical payload>"
}

Compliance posture

Webhook delivery inherits the same regulated posture as the rest of the payment platform: Taiwan VASP, ISO 27001 and ISO 27701 certifications, SOC 2 Type II, Cure53 audit. Signing keys are managed per organisation and can be rotated. See Compliance and Certifications for the full picture.

Typical integration timeline

PhaseBucket
Wire the callback URL on payment intents and verify the HMAC signature in your receiverUnder one month — typically a few days for a backend team comfortable with HMAC verification
Add a callback delivery log review and a reconciliation job that polls the intent endpoint as a backstopUnder one month
Custodial-transfer (Asset Pro) callbacks once shippedRoadmap — see Current scope

Current scope

  • Payment-intent callbacks with HMAC-SHA256 signing and a five-minute timestamp validity window are in production.
  • Delivery is best-effort. Treat the callback as a notification; the payment intent endpoint remains the source of truth, and your integration should include a reconciliation path for missed deliveries.
  • Custodial-transfer (Asset Pro) callbacks are on the near-term roadmap. Today, partners poll the transfer-history endpoint to learn when a custodial transfer has settled.
  • A self-service webhook subscription model — where you register one organisation-wide URL with per-event-type filtering and a delivery dashboard — is in design. Today the URL is set per payment intent.
  • Per-organisation signing-secret management is on the near-term roadmap. Today the signing secret is configured as part of the partner-facing application credential issued during onboarding; rotation is handled through your KryptoGO partner contact.

Talk to us

If you want to integrate signed webhooks for the payment platform or scope the upcoming custodial-transfer notifications, the fastest way to start is a 45-minute discovery call. Reach our partnerships team via the address on www.kryptogo.tw .

Where to go next

Last updated on
On-Chain Analytics & Token SignalsOverview