Webhooks are the primary notification channel. Polling is the recovery and audit path — not a substitute for push.
Example#
curl -s -X GET "https://api.avrix.io/api/seller/v1/events?limit=100" \
-H "Authorization: Bearer $AVRIX_API_KEY"Cursors. Make the first call without cursor (or with since=<ISO8601>); cursor only
accepts a value the API returned. Each page answers meta.nextCursor (another page is waiting:
call again with it straight away) and meta.headCursor (the resume position, present at the head
too). Store headCursor after every page and pass it as cursor on your next poll: an empty page
at the head returns the same headCursor, so you never lose your place. Deliveries of a deleted
webhook endpoint stay on this feed. meta also carries limit, hasMore and nextUrl, like
every list (Lists and pagination).
Design for both: consume signed webhooks in real time, and run scheduled pulls so a missed delivery never strands a paid buyer.
Why webhook-first#
| Benefit | Explanation |
|---|---|
| Latency | Order events reach your backend without waiting for a cron tick |
| Key material | Persist keys from POST /orders; webhooks and GET /orders never echo plaintext |
| Clarity | At-least-once delivery with a stable eventLogId for dedupe, the same id the event log uses |
Recovery surfaces#
| Layer | Endpoint | Typical use |
|---|---|---|
| Order aggregates | GET /api/seller/v1/orders?orderReference=store-order-10432 | Support lookup, webhook gap recovery |
| Order listing | GET /api/seller/v1/orders?from=&to=&cursor=&limit= | Full-ledger reconciliation and disaster recovery |
| Catalog deltas | GET /api/seller/v1/catalog/changes?cursor= (or since=) | Catch product/pricing changes and tombstones after outages — changedFields: ["pricing"] is the only poll surface for price changes |
| Webhook deliveries | GET /api/seller/v1/webhooks/{id}/deliveries | Inspect pending / failed attempts in the retry window |
| Delivery replay | POST /api/seller/v1/webhooks/{id}/deliveries/replay | Re-send after your endpoint was down — new eventId, the same eventLogId, with replay markers |
| Event log | GET /api/seller/v1/events?cursor= | Contract date 2026-12-01 and later: every event of the last 30 days, one row each, whether or not an endpoint subscribes; filter by eventType, resourceType, resourceId. Earlier dates: a forward-only cursor over webhook delivery rows |
| Request trace | GET /api/seller/v1/requests/{requestId} | Correlate X-Request-Id from errors |
Missed webhook recovery#
- Confirm the endpoint failure in GET /webhooks/{id}/deliveries (status, response code, timestamps).
- Replay with POST /webhooks/{id}/deliveries/replay when the original is still in the replay window. Replays carry a fresh
eventIdand the originaleventLogId, so a handler that dedupes oneventLogIdskips what it already applied. On contract date2026-12-01and later you can instead read GET /events from your storedmeta.headCursor: it lists the events of the outage, including those of types no endpoint subscribed to. - For orders, call
GET /api/seller/v1/orders?orderReference=store-order-10432and compare aggregates to your OMS. - For catalog drift, call
GET /api/seller/v1/catalog/changes?cursor=<last applied cursor>(orsince=<ISO8601>) and apply tombstones / updates; refetch only the facets named inchangedFields(pricing→GET /products/{id}/pricing). GET /catalog/checksum returns your currentchangesCursor— when it differs from the one you applied, deltas are waiting. - Escalate with
X-Request-Id,orderReference, and timestamps when aggregates disagree past your SLA.
Periodic reconciliation job#
Run this even when webhooks look healthy (“trust but verify”).
Suggested daily (or hourly for high volume) loop:
- Page
GET /api/seller/v1/orders?from=<window start>&to=<window end>&limit=100withmeta.nextCursoruntil it isnull— this is Avrix's authoritative list of your fulfilled orders in the window (each row carriesorderReference, derivedstatus,skuId,quantity,fulfilledAt, andkeyIds— key ids, never plaintext). - Diff both ways against your storefront charges for the same window:
- Orphan PSP captures (charge with no Avrix row) — investigate or refund at your PSP.
- Orphan Avrix rows (row with no storefront order) — investigate duplicate idempotency misuse.
- For any row in an unexpected state, drill in with
GET /api/seller/v1/orders?orderReference=…(aggregate includesrefunds[]). If you addstatus=to the listing in step 1, check which values your environment can serve first: see Filtering the listing by status. On contract date2026-12-01and later a value it cannot serve is a422; on earlier dates it is an empty page that looks like "no orders". - Optionally sweep GET /api/seller/v1/events from your stored cursor for events you never
processed (on contract date
2026-12-01and later; earlier dates list delivery rows).
Ledger rebuild (disaster recovery)#
After a total store-DB loss, rebuild the complete order ledger from the API alone: page the
listing from your integration launch date to now (from=<launch>&limit=100, follow
meta.nextCursor). Every row maps back to your store order via orderReference; re-request key
material only where the buyer never received it, via the
key recovery runbook — the listing itself never returns plaintext.
Partners without inbound webhooks#
If policy forbids inbound HTTP:
- On purchase, POST /orders with
Idempotency-Key+orderReference→ persist response entitlements immediately. - Poll
GET /orders?orderReference=…until terminal aggregates match. - Follow
GET /eventswithX-Avrix-Api-Version: 2026-12-01or later: every event Avrix raises for you is in it whether or not you have a webhook endpoint. Storemeta.headCursorafter each page and send it back ascursoron the next poll; poll at least once a day, since events are kept 30 days. - On mismatch past SLA, escalate with
X-Request-Id. - On finance cycle, reconcile transactions / finance exports independently of webhooks.
Things that need your attention#
Some events ask a person on your side to act. On contract date 2026-12-01 and later one filtered
poll lists them, whether or not you subscribed to them:
curl -s -G "https://api.avrix.io/api/seller/v1/events" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "X-Avrix-Api-Version: 2026-12-01" \
--data-urlencode "eventType=access.proposal_created,return.information_requested,return.decided,allocation.request_decided,contract.expiring,connection.suspended,invoice.issued" \
--data-urlencode "cursor=$LAST_HEAD_CURSOR"
| Event | What to do |
|---|---|
access.proposal_created | Accept or decline the proposal (POST /access/proposals/{id}/accept or /decline) |
return.information_requested | Answer the Content Owner about the return request |
return.decided | Settle with the buyer as resolution says |
allocation.request_decided | List the SKU, or tell whoever filed the request it was denied |
contract.expiring | Ask the Content Owner to renew before validUntil |
connection.suspended | Pause sales of that Content Owner's SKUs |
invoice.issued | Book and pay the invoice |
The feed tells you what happened, not what is still open: an item stays open until you act on it,
and the feed does not mark it done. Keep your own list of open items, keyed by the event's
resourceId, and close each one when you act.
Latency realism#
Catalog-class events may arrive on a minute-scale freshness budget. Order hot-path recovery should use order aggregates and delivery replay first, not full catalog polls.