WebhooksOverview

Webhooks

TradeOn POSTs JSON events to the URL you configure in the cabinet (Settings → Webhook) when a merchant order changes state or a balance deposit completes. No per-event subscription — the URL receives everything.

What you need to get right before going live:

  • Verify X-Signature and reject X-Timestamp skewed by more than ±5 min — Signature.
  • Return 2xx within ~10 s. 5xx / timeouts auto-retry, 4xx does not — Retry policy.
  • Dedup on (purchase_id, event) for purchase.*, on data.provider_uuid for balance.deposited — Dedup contract.
  • Tolerate unknown event types and unknown fields (return 2xx) — Versioning.

Headers on every delivery

HeaderValue
Content-Typeapplication/json; charset=utf-8
User-AgentTradeOn-Merchant-Webhook/1.0
X-EventEvent type, e.g. purchase.completed (matches the event field in the body).
X-Event-IdServer-generated UUID, also present as event_id in the body. Stable across retries.
X-TimestampUnix seconds at delivery time (regenerated per attempt, signed payload).
X-Signaturehex(HMAC-SHA256(secret, "{X-Timestamp}.{raw_body}")), lowercase hex.

The body is always a JSON envelope:

{
  "event": "purchase.completed",
  "event_id": "11111111-2222-3333-4444-555555555555",
  "occurred_at": "2026-05-05T12:34:56.789Z",
  "data": { /* event-specific payload */ }
}

Six event types in v1

  • purchase.created
  • purchase.sent_to_steam
  • purchase.completed
  • purchase.failed
  • purchase.refunded
  • balance.deposited

See Event Catalogue for per-event payload schemas.

Webhook EventsEvent Catalogue