Events & updates
Choose a channel by the state you need to keep current. Both complement the REST API.
| Your data | Channel | Who connects? | Recovery |
|---|---|---|---|
| Available offers, prices, additions, removals | Catalog updates · WebSocket | Your server opens an authenticated connection to TradeOn. | Resume with the last applied cursor; download a new snapshot when resync is required. |
| Purchase delivery, failures, refunds, balance credits | Purchases & balance · Webhooks | TradeOn sends signed HTTP POST requests to your HTTPS endpoint. | Accept duplicates safely, check the delivery log, and reconcile purchases through REST. |
Catalog updates · WebSocket
Begin with Synchronize the catalog. A complete snapshot provides items and a cursor/epoch checkpoint. Replay the retained changes, then continue with live batches. Send the required JSON pong and save progress only after applying each batch.
The WebSocket reference defines frames, event fields, close codes, replay limits, and resync. These updates describe offers; they do not confirm a purchase.
Purchases & balance · Webhooks
Start with Webhooks, then verify signatures and implement delivery and recovery. Acknowledge a valid event only after durable acceptance; acknowledge already accepted duplicates with 2xx as well.
The event catalog defines all eight event types. Delivery can repeat or
arrive out of order. purchase.completed confirms delivery, but a later protection rollback
can still occur. Keep REST purchase status available for reconciliation.
A webhook event ID identifies a notification. It is unrelated to a catalog cursor, and its acknowledgement does not use WebSocket pong or cursor rules.