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.
Verify and durably accept the event before returning 2xx; aim for ~10 seconds. Valid, already-accepted duplicates also receive 2xx without another business effect.
Keep a durable inbox keyed by event_id, then dedup purchase effects on (purchase_id, event) and deposits on data.provider_uuid — Dedup contract.
5xx, timeouts, HTTP 408 and 429 are retried within a finite retry window. Other 4xx stop automatic delivery — Retry policy.
Tolerate unknown event types and unknown fields (return 2xx) — Versioning.

Delivery can be repeated or arrive out of order. purchase.completed means the item was delivered; a later protection rollback is still possible. Reconcile purchases and balance with REST instead of using webhooks as your only accounting record. For prices and catalog availability, use the separate WebSocket feed.

Headers on every delivery

Header	Value
`Content-Type`	`application/json; charset=utf-8`
`User-Agent`	`TradeOn-Merchant-Webhook/1.0`
`X-Event`	Event type, e.g. `purchase.completed` (matches the `event` field in the body).
`X-Event-Id`	Server-generated UUID, also present as `event_id` in the body. Stable across retries.
`X-Timestamp`	Unix seconds at delivery time (regenerated per attempt, signed payload).
`X-Signature`	`hex(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": {
    "purchase_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "custom_id": "your-order-42",
    "completed_at": "2026-05-05T12:34:56.789Z"
  }
}

Eight event types in v1

purchase.created
purchase.sent_to_steam
purchase.completed
purchase.failed
purchase.refunded
purchase.reverted_by_buyer
purchase.reverted_by_seller
balance.deposited

See Event Catalogue for per-event payload schemas.

Catalog updates · WebSocket Event Catalogue