Polling & reconciliation

Recover from missed webhooks with deliveries replay and order reads.

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#

BenefitExplanation
LatencyOrder events reach your backend without waiting for a cron tick
Key materialPersist keys from POST /orders; webhooks and GET /orders never echo plaintext
ClarityAt-least-once delivery with a stable eventLogId for dedupe, the same id the event log uses

Recovery surfaces#

LayerEndpointTypical use
Order aggregatesGET /api/seller/v1/orders?orderReference=store-order-10432Support lookup, webhook gap recovery
Order listingGET /api/seller/v1/orders?from=&to=&cursor=&limit=Full-ledger reconciliation and disaster recovery
Catalog deltasGET /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 deliveriesGET /api/seller/v1/webhooks/{id}/deliveriesInspect pending / failed attempts in the retry window
Delivery replayPOST /api/seller/v1/webhooks/{id}/deliveries/replayRe-send after your endpoint was down — new eventId, the same eventLogId, with replay markers
Event logGET /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 traceGET /api/seller/v1/requests/{requestId}Correlate X-Request-Id from errors

Missed webhook recovery#

  1. Confirm the endpoint failure in GET /webhooks/{id}/deliveries (status, response code, timestamps).
  2. Replay with POST /webhooks/{id}/deliveries/replay when the original is still in the replay window. Replays carry a fresh eventId and the original eventLogId, so a handler that dedupes on eventLogId skips what it already applied. On contract date 2026-12-01 and later you can instead read GET /events from your stored meta.headCursor: it lists the events of the outage, including those of types no endpoint subscribed to.
  3. For orders, call GET /api/seller/v1/orders?orderReference=store-order-10432 and compare aggregates to your OMS.
  4. For catalog drift, call GET /api/seller/v1/catalog/changes?cursor=<last applied cursor> (or since=<ISO8601>) and apply tombstones / updates; refetch only the facets named in changedFields (pricing → GET /products/{id}/pricing). GET /catalog/checksum returns your current changesCursor — when it differs from the one you applied, deltas are waiting.
  5. 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:

  1. Page GET /api/seller/v1/orders?from=<window start>&to=<window end>&limit=100 with meta.nextCursor until it is null — this is Avrix's authoritative list of your fulfilled orders in the window (each row carries orderReference, derived status, skuId, quantity, fulfilledAt, and keyIds — key ids, never plaintext).
  2. 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.
  3. For any row in an unexpected state, drill in with GET /api/seller/v1/orders?orderReference=… (aggregate includes refunds[]). If you add status= to the listing in step 1, check which values your environment can serve first: see Filtering the listing by status. On contract date 2026-12-01 and later a value it cannot serve is a 422; on earlier dates it is an empty page that looks like "no orders".
  4. Optionally sweep GET /api/seller/v1/events from your stored cursor for events you never processed (on contract date 2026-12-01 and 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.

Diagram

Partners without inbound webhooks#

If policy forbids inbound HTTP:

  1. On purchase, POST /orders with Idempotency-Key + orderReference → persist response entitlements immediately.
  2. Poll GET /orders?orderReference=… until terminal aggregates match.
  3. Follow GET /events with X-Avrix-Api-Version: 2026-12-01 or later: every event Avrix raises for you is in it whether or not you have a webhook endpoint. Store meta.headCursor after each page and send it back as cursor on the next poll; poll at least once a day, since events are kept 30 days.
  4. On mismatch past SLA, escalate with X-Request-Id.
  5. 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:

Bash
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"
EventWhat to do
access.proposal_createdAccept or decline the proposal (POST /access/proposals/{id}/accept or /decline)
return.information_requestedAnswer the Content Owner about the return request
return.decidedSettle with the buyer as resolution says
allocation.request_decidedList the SKU, or tell whoever filed the request it was denied
contract.expiringAsk the Content Owner to renew before validUntil
connection.suspendedPause sales of that Content Owner's SKUs
invoice.issuedBook 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.

What links here

Published guides that link to this page.

Search docs

Search documentation…