Webhooks tell your storefront what happened after the request finished: an order fulfilled, a preorder released, an allocation depleted, a refund completed. This page covers building a consumer that verifies signatures correctly, tolerates duplicates and reordering, and recovers from missed deliveries.
Delivery and retry lifecycle#
If you implement only one thing from this page, implement signature verification.
Registering an endpoint#
curl -s -X POST "https://api.avrix.io/api/seller/v1/webhooks" \
-H "Authorization: Bearer avrix_sk_your_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-create-1" \
-d '{
"url": "https://store.example.com/avrix/webhooks",
"events": ["order.fulfilled", "order.failed", "allocation.depleted"]
}'
{
"data": {
"id": "7d3f2a1c-9b4e-4f60-8a2d-5c1e3b7f9a04",
"url": "https://store.example.com/avrix/webhooks",
"events": ["order.fulfilled", "order.failed", "allocation.depleted"],
"secret": "whsec_2fA9x...",
"deliveryProbe": { "reachable": true, "statusCode": 200, "error": null }
}
}
The call answers 201. id is a UUID: use it in every /webhooks/{id} path. deliveryProbe
is one reachability check of your URL made at registration (a HEAD request with a 5-second
limit); it is informational, and a failed probe does not block the registration. The answer also
carries the endpoint's status, createdAt, delivery health and queue counters, the same fields
GET /webhooks and GET /webhooks/{id} return. Registration needs at least
one active agreement with a vendor; without one it answers 409 NO_ACTIVE_BMA.
Requirements: the URL must be HTTPS and publicly reachable, with no username or password in it
(https://user:pass@… is refused with 422; authenticate deliveries with the signature, not
Basic auth). IP-literal hosts in private, loopback, link-local or reserved ranges are refused in
every spelling, including IPv4-mapped IPv6 ([::ffff:<IPv4>]) and NAT64, 6to4 and Teredo
prefixes; the same rules are applied again to every resolved address at delivery. Subscribe only to events you handle;
subscribing to everything and ignoring most of it wastes your capacity and obscures real failures.
events takes event names and two kinds of wildcard: * (every event, including event types
added later) and <family>.*, such as order.* or allocation.* (every event of one family, the
part of the name before the dot). One event reaches an endpoint once, however many of its entries
match. The older alias order.returned is sent only to endpoints that name it; order.* receives
the same event as order.cancelled.
Scope: seller:webhooks:write to manage endpoints, seller:webhooks:read to list deliveries.
Delivery format#
Avrix POSTs JSON with these headers:
| Header | Purpose |
|---|---|
X-Avrix-Signature | HMAC-SHA256 in the form t=<unix-seconds>,v1=<hex> |
X-Avrix-Signature-Version | Currently 1 |
X-Avrix-Event-Version | Payload schema version, currently 1 |
X-Avrix-Event-Log-Id | The event's own id — use this for deduplication. One value per event: the same on every endpoint that receives it, on retries and on replays, and the event's id in GET /events. Absent on test deliveries |
X-Avrix-Event-Id | Id of this delivery. It is minted per delivery: the same event sent to two of your endpoints carries a different id on each, and a replay carries a new one |
X-Avrix-Delivery-Id | The delivery row, as GET /webhooks/{id}/deliveries lists it; quote it when you report a delivery problem |
X-Avrix-Event-Type | Event name, matching your subscription |
User-Agent | Avrix-Webhooks/1 — allow it if your WAF or proxy filters on user agent |
Body — one flat JSON object. eventId, eventLogId, eventType, eventVersion (a string)
and occurredAt (when the event happened) sit next to the event's own fields; there is no data
wrapper. eventId carries the same value as the X-Avrix-Event-Id header and eventLogId the
same value as X-Avrix-Event-Log-Id. Every id, replays and test pings included, has the evt_
form:
{
"eventId": "evt_1754385262108_9f2c4b1e7a3d5c60",
"eventLogId": "evt_1754385262101_3b7e0c9a5d1f2e84",
"eventType": "order.fulfilled",
"eventVersion": "1",
"occurredAt": "2026-08-05T09:14:22.108Z",
"orderReference": "store-order-10432",
"orderId": "ord_6rfz4y3b",
"orderReadableId": "ord_6rfz4y3b",
"allocationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"pulled": 1
}
Per-event fields are listed in the Event reference and typed in the
OpenAPI webhooks section. A replayed delivery carries a fresh eventId, the original
eventLogId, and a top-level replay object with sourceDeliveryId and originalEventId — see
the replay window below. A test
delivery from POST /webhooks/{id}/test (other than a plain test.ping) carries a top-level
testEvent object with testRunId and, for a receiver challenge, challenge — see
Testing. Never apply a testEvent delivery to your records.
Verifying signatures#
Verify before you parse. An unverified webhook is untrusted input from the open internet, and your handler performs money-relevant side effects.
The signature is computed as HMAC-SHA256(secret, "{timestamp}.{raw_body}"), hex-encoded.
Three rules that are easy to get wrong:
- Use the raw request body bytes. Not a re-serialised object. Most frameworks parse JSON before your handler runs — you must configure a raw-body reader. Re-serialising changes whitespace and key order, and the signature will never match.
- Compare in constant time. A naive
==leaks timing information. - Enforce the timestamp tolerance. Default 300 seconds (5 minutes). Without it, a captured payload can be replayed indefinitely.
# Verification is server-side in your webhook handler — not a curl call.
# Header: X-Avrix-Signature: t=<unix>,v1=<hex>[,v1=<hex>] (two v1 during a secret rotation; accept either)
# Signed payload: "{t}.{rawBody}" with HMAC-SHA256 and your endpoint secret.Express (Node)#
# Webhook handlers are inbound — register the URL with POST /webhooks, then verify signatures in your app.FastAPI (Python)#
# Inbound webhook — not invoked via curl from your store.Laravel (PHP)#
# Inbound webhookSpring (Java)#
# Inbound webhookASP.NET (C#)#
# Inbound webhookExpress handler with a raw body (TypeScript):
import express from "express";
const app = express();
app.post(
"/avrix/webhooks",
express.raw({ type: "application/json" }),
async (req, res) => {
const rawBody = req.body.toString("utf8");
const valid = verifyAvrixWebhook(
rawBody,
req.header("X-Avrix-Signature") ?? null,
process.env.AVRIX_WEBHOOK_SECRET!
);
if (!valid) return res.status(400).send("invalid signature");
const event = JSON.parse(rawBody);
// Acknowledge fast; process out of band.
res.status(200).send("ok");
await enqueue(event);
}
);
The TypeScript SDK helpers (@avrix/seller-api-helpers; see Official SDKs for
availability) implement the same algorithm using Web Crypto, so it runs on Node, edge runtimes,
and workers.
Responding#
Return 2xx as soon as the signature verifies. Do your real work asynchronously — enqueue the
event and process it in a worker.
Anything non-2xx, or a response that exceeds the 8-second delivery timeout, is treated as a
failed delivery and triggers the retry schedule. Avrix only reads a short slice of your response
body for diagnostics (a few hundred bytes); keep acknowledgements tiny (ok / empty body).
A handler that does database writes and outbound calls inline will eventually time out under load, and Avrix will retry, and you will process the same event repeatedly.
Retries#
A delivery gets at most nine attempts, spanning roughly 45 hours end to end — an endpoint outage of a full day still receives every event without manual replay:
| Attempt | Delay after previous |
|---|---|
| 1 | immediate |
| 2 | 30 seconds |
| 3 | 2 minutes |
| 4 | 10 minutes |
| 5 | 1 hour |
| 6 | 2 hours |
| 7 | 6 hours |
| 8 | 12 hours |
| 9 | 24 hours |
The ninth attempt is terminal — if it fails the delivery is marked failed and is not retried
automatically. Use POST /webhooks/{id}/deliveries/{deliveryId}/retry or bulk replay after you
recover, and reconcile with GET /orders and GET /catalog/changes?since= for anything outside
retained delivery history.
Operational contract#
Delivery timeout#
Avrix waits up to 8 seconds for your HTTPS response. Exceeding that window counts as a failed
attempt (same as a non-2xx) with lastError: timeout, and the delivery is retried on the schedule
above. Acknowledge with 2xx first and do the work asynchronously.
A slow receiver does not delay anyone else's deliveries. Each endpoint gets its own share of every delivery run. An endpoint whose attempts are timing out is sent one delivery per run until it answers in time again, so its backlog drains without holding other endpoints back.
Early warning: failing endpoints#
The circuit breaker below needs ten deliveries to exhaust their retries, which takes about 45 hours
of a broken receiver. Long before that, an endpoint becomes failing: as soon as at least 3
attempts in a row have failed and the run of failures has lasted at least 10 minutes. The
endpoint stays active and retries continue; nothing else changes.
When an endpoint becomes failing, Avrix:
- records
system.webhook_endpoint_failingon your event log, soGET /events(contract date2026-12-01and later) has it even when every endpoint you have is down; - delivers the same event to your endpoints that subscribe to it;
- posts an in-app console notification to company admins.
It is sent once per episode. The first attempt your endpoint answers with 2xx ends the episode and
sends system.webhook_endpoint_recovered. GET /webhooks and GET /webhooks/{id} show the state
on every endpoint: failing, failingSince, lastSuccessAt, lastFailureAt and
consecutiveFailedAttempts. Test sends and sandbox receiver challenges do not count toward it.
Auto-disable (circuit breaker)#
After 10 consecutive terminal failures (deliveries that exhaust the full retry schedule), the
endpoint status becomes disabled with reason consecutive_delivery_failures. A successful
delivery resets the consecutive-failure streak.
Partner notification: the breaker never trips silently. On the active → disabled
transition Avrix (1) delivers a signed system.webhook_endpoint_disabled event to your
company's endpoints, (2) posts an in-app console notification to company admins, and (3) emails
company admin addresses. Fix your receiver, then re-enable with POST /webhooks/{id}/enable
(or the Console).
The event's disabledAt is the moment the breaker opened. Because the same event is
buffered for the disabled endpoint itself, it is delivered to that endpoint after you
re-enable it — ignore it when disabledAt predates your last enable, or re-read the endpoint with
GET /webhooks/{id} before acting on it.
The breaker's thresholds are unchanged by the failing signal above: failing warns you, it never
disables an endpoint.
Events while the endpoint is disabled#
New events are buffered, not lost: deliveries for a disabled endpoint are parked and flushed
automatically when the endpoint is re-enabled (POST /webhooks/{id}/enable responds with
flushedBufferedDeliveries). Deliveries already pending when the endpoint was disabled are
buffered the same way on their next sweep.
Avrix alerts your company admins (console notification, plus email from 80%) when a disabled
endpoint's buffer crosses 50%, 80%, and 100% of its cap, and the webhook listing
(GET /api/seller/v1/webhooks) reports bufferedDeliveries / bufferCapacity per endpoint so
you can watch the depth yourself.
The buffer is capped at 10,000 events per endpoint. Beyond the cap, new events for that
endpoint are dropped — recover via polling (GET /orders?orderReference=…,
GET /catalog/changes?since=, allocations) after re-enabling. Do not treat the buffer as an
unbounded queue: re-enable promptly after fixing your receiver.
Pausing an endpoint#
POST /webhooks/{id}/disable pauses an active endpoint yourself, for example during a deployment
of your receiver. Nothing is sent to it until you resume; events that happen meanwhile are buffered
exactly as above (disabledReason is manual), and GET /events keeps every event. A pause raises
no alert. Pausing an endpoint that is already disabled changes nothing (alreadyDisabled: true).
Before resuming, check the receiver: on contract date 2026-12-01 and later
POST /webhooks/{id}/test sends one test delivery to a disabled endpoint without re-enabling it.
It is not retried and does not count toward the endpoint's health. Earlier dates answer 400
for a disabled endpoint.
POST /webhooks/{id}/enable resumes and sends every buffered event. To resume without the backlog,
send the instant from which you want events:
curl -s -X POST "https://api.avrix.io/api/seller/v1/webhooks/7d3f2a1c-9b4e-4f60-8a2d-5c1e3b7f9a04/enable" \
-H "Authorization: Bearer avrix_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "replayFrom": "2026-11-13T09:00:00Z" }'
Buffered events created before replayFrom are not sent: they are closed as failed with
lastError: skipped_on_enable and counted in skippedBufferedDeliveries. They stay in the
delivery log, so retry or replay can still send any of them, and GET /events still has them.
replayFrom must be a date-time that is not in the future (422 otherwise). Without it, enable
behaves as it always has.
Replay window and delivery history#
- Bulk replay (
POST /webhooks/{id}/deliveries/replay) accepts asince/untilwindow of at most 7 days and up to 1,000 source deliveries per call (default limit 200). When the window holds more thanlimit, the response sayshasMore: trueand givesnextSince: call again withsinceset to it to replay the rest. Deliveries created at that exact instant are matched again by the next call. - Send an
Idempotency-Keywith a replay and reuse it on retries: a retry with the same key and body answers with the first call's result and clones nothing again. - On contract date
2026-12-01and later a replay never clones a delivery that is itself a replay or a test delivery, so replaying the same window twice does not multiply deliveries. Earlier contract dates clone every matching delivery. - A replayed delivery carries a NEW
X-Avrix-Event-Idand the SAMEX-Avrix-Event-Log-Id. It is a new delivery of the same event. Deduplicating oneventLogId, as recommended above, makes replay idempotent: a replayed event you already applied is recognised. If you deduplicate oneventId, a replay runs your handler again, which is what you want only when you replay to re-apply events. - Every replayed delivery also carries a top-level
replayobject withreplay.originalEventId(theeventIdof the original delivery) andreplay.sourceDeliveryId(the original delivery row). For deliveries without aneventLogId,event.replay?.originalEventId ?? event.eventIdis the stable key. - List deliveries returns the newest rows first (default 50, max 100 per page) and pages through
the whole retained history like every list (Lists and pagination). Each row
carries the event's
eventLogId. - Retention: finished delivery rows (
succeededorfailed) are kept 30 days, then deleted by a daily job; the full replay window is always recoverable. Pending and buffered deliveries are never deleted, whatever their age. The event log (GET /events) is kept 30 days too.
Delivery log#
GET /webhooks/{id}/deliveries/{deliveryId} shows one delivery in full:
body: the JSON your endpoint received, the same on every attempt;headers: the identifying headers sent with it (the signature is computed per attempt and not shown);responseBodyExcerpt: your endpoint's last answer;attemptHistory: one entry per attempt, oldest first, withattemptedAt,outcome,responseStatus,responseBodyExcerpt,erroranddurationMs.
Answers are kept to at most 500 characters, and credentials your endpoint echoed back (webhook
secrets, API keys, bearer and basic credentials, JWTs, and password, secret, token,
api_key, authorization or signature fields in JSON) are masked before they are stored.
Attempts made before 13 November 2026 have no history entries; the delivery's own counters still
apply. The delivery is readable after its endpoint is deleted (meta.endpointDeleted).
Management routes#
| Method | Path | Purpose |
|---|---|---|
GET | /api/seller/v1/webhooks/{id} | One endpoint: subscription, status, delivery health and queue |
POST | /api/seller/v1/webhooks/{id}/disable | Pause an endpoint; events are buffered until you enable it |
POST | /api/seller/v1/webhooks/{id}/enable | Re-enable after circuit-breaker or manual disable (clears failure streak); replayFrom skips older buffered events |
POST | /api/seller/v1/webhooks/{id}/deliveries/{deliveryId}/retry | Re-queue a failed delivery (fresh attempt cycle); returns 202 |
GET | /api/seller/v1/webhooks/event-types | Catalog of event names and short descriptions for subscription discovery |
GET | /api/seller/v1/webhooks/{id}/deliveries | Delivery history (attempts, status codes) |
GET | /api/seller/v1/webhooks/{id}/deliveries/{deliveryId} | One delivery: body, headers, last answer and every attempt |
POST | /api/seller/v1/webhooks/{id}/deliveries/replay | Bulk clone deliveries in a time window (fresh eventId; correlate via the top-level replay object) |
POST | /api/seller/v1/webhooks/{id}/test | Signed test.ping; with a sandbox key, any event type and receiver challenges |
PATCH / DELETE | /api/seller/v1/webhooks/{id} | Update or remove an endpoint |
GET | /api/seller/v1/events | Your event feed. On contract date 2026-12-01 and later: every event, one row each, whether or not an endpoint subscribes, kept 30 days, filterable by eventType, resourceType and resourceId (Event log). Earlier dates: one row per webhook delivery. Page with meta.nextCursor (keyset), not since alone: a burst of events sharing one timestamp cannot be paged by time. |
Scopes: seller:webhooks:write for enable/disable/retry/replay/test/mutate; seller:webhooks:read
for list, single endpoint, deliveries, event-types, and GET /events.
Egress IP allowlisting#
GET /api/seller/v1/webhooks/egress-ips (key-free) publishes the webhook delivery egress
identity: { egressIps: [], pinned: false, verificationRequired: true }.
- When
pinnedis true, the listed addresses are stable; any change is announced in the Changelog at least 14 days in advance — re-read the endpoint on a schedule rather than hardcoding. - When
pinnedis false (the current default — delivery egress is not pinned on this infrastructure), do not build source-IP allowlists. Signature verification is the authoritative control either way; strict-firewall partners who require pinned IPs or mTLS delivery should contact support@avrix.io.
Payload size and endpoints#
- Seller API request bodies (including webhook create/patch/replay) are capped at the platform
100 KB request-body limit (
413PAYLOAD_TOO_LARGE when exceeded). - Each endpoint’s
eventsarray must be non-empty, unique, and made of names from the published event catalog (GET /webhooks/event-types) or wildcards (*,<family>.*). - Endpoint limit: on contract date
2026-12-01and later a company registers at most 16 endpoints (active and disabled; for a sandbox key, per key). A seventeenth answers 409 WEBHOOK_ENDPOINT_LIMIT_REACHED. Endpoints that already exist above the limit keep working, and earlier dates have no limit. Use wildcards rather than one endpoint per event.
Webhook management traffic on sandbox keys shares the sandbox abuse cap under the webhooks management class — see Rate limits.
Delivery guarantee#
What Avrix promises, precisely:
- Recorded events are delivered at least once. Once an event is on your event log, every
endpoint subscribed to it at that moment gets a delivery row, which is attempted on the retry
schedule above, buffered while the endpoint is disabled (up to the buffer cap) and kept 30 days.
Retry, replay and
GET /eventsrecover anything an endpoint missed. - Recording follows the change, it is not part of it. An event is recorded right after the change it reports has been saved, not in the same transaction. If Avrix fails in the moment between the two, the change stands and the event is missing from the log and from webhooks. This is rare, and it is the reason the reconciliation job below is not optional: order state from GET /orders, allocations and the catalog change feed are the system of record.
- No order between events (next section), and no exactly-once: deduplicate on
eventLogId.
Duplicates and ordering#
Delivery is at-least-once. You will receive duplicates. This is normal and not an error.
Events are not globally ordered. A retry of an earlier event can arrive after a later one.
Both are handled by the same pattern: deduplicate on eventLogId (X-Avrix-Event-Log-Id) and
make handlers idempotent. eventLogId is the same for one event on every endpoint, retry and
replay, so two endpoints that share one store database apply each event once.
async function handleEvent(event: AvrixEvent) {
// eventLogId is absent only on test deliveries and on deliveries older than the event log.
const key = event.eventLogId ?? event.replay?.originalEventId ?? event.eventId;
const seen = await db.webhookEvents.findUnique({ where: { eventId: key } });
if (seen) return;
await db.$transaction(async (tx) => {
await tx.webhookEvents.create({ data: { eventId: key, type: event.eventType } });
await applyEvent(tx, event);
});
}
Record the event id and apply the effect in the same transaction. Recording first and applying after leaves a window where a crash loses the effect permanently.
For ordering, make each handler evaluate current state rather than assume a sequence. An
allocation.depleted that arrives after an allocation.updated should cause a re-read of
allocations, not a blind decrement.
The webhook may arrive first#
order.fulfilled can reach your endpoint before POST /orders returns to your checkout process.
There is no guaranteed ordering between an HTTP response and its webhook.
Design your handler to tolerate an order it has not recorded yet: buffer the event for a short retry, or create the record from the webhook and reconcile when the HTTP response lands. Never error out on "unknown order" — that turns a benign race into a failed delivery and a retry storm.
Rotating the secret#
curl -s -X PATCH "https://api.avrix.io/api/seller/v1/webhooks/7d3f2a1c-9b4e-4f60-8a2d-5c1e3b7f9a04" \
-H "Authorization: Bearer avrix_sk_your_key_here" \
-H "Idempotency-Key: rotate-webhook-7d3f2a1c-2026-11" \
-H "Content-Type: application/json" \
-d '{ "rotateSecret": true }'
Send an Idempotency-Key with the rotation and reuse it if you retry: a retry with the same key
does not rotate again, it answers with the secret the first call minted (Idempotency-Replayed: true). If the endpoint has been rotated again since, that secret is no longer in use and the
replay answers secretRedacted: true instead. Without a key every call with rotateSecret: true
issues a new secret, and only the newest secret and the one before it verify, so a retry of a call
whose response was lost replaces the secret you never received: store the one the retry returns.
previousSecretExpiresAt in the response says until when the replaced secret still signs. The new secret is returned once. The previous secret stays valid for 48 hours, and during that
window deliveries carry two v1= values — one per secret, the current secret's first and
the previous secret's second: t=1754385262,v1=<current>,v1=<previous>. The verification code
above checks every v1= value present, which is why it is written as a loop rather than a single
comparison: a verifier that keeps only one value (a dictionary built from the header keeps the
last) compares against the previous secret only, and rejects every delivery once you switch.
Sequence: store the new secret and verify with it (the loop accepts the delivery through either
v1=), keep the old one until the window closes, then drop it after 48 hours. The
@avrix/seller-api-helpers verifyAvrixWebhookSignature checks every v1= too.
Testing#
Send a test delivery:
curl -s -X POST "https://api.avrix.io/api/seller/v1/webhooks/7d3f2a1c-9b4e-4f60-8a2d-5c1e3b7f9a04/test" \
-H "Authorization: Bearer avrix_sk_your_key_here"
Your endpoint receives a signed test.ping. Verify that:
- the signature validates;
- a deliberately corrupted signature is rejected — an endpoint that accepts everything is worse than no verification, and this is the test most integrations skip;
- an old timestamp is rejected;
- a duplicate
eventIdis ignored; - your handler responds within your timeout budget.
Inspect delivery history with GET /api/seller/v1/webhooks/{id}/deliveries to see attempts, status
codes, and failures.
Test events and receiver challenges (sandbox keys)
With a sandbox key, the same call accepts an optional JSON body that lets you rehearse every handler and every rejection rule above without waiting for real traffic:
| Field | Values | Effect |
|---|---|---|
eventType | Any Seller API event name (default test.ping) | Sends a contract-valid sample payload for that event, built from the sandbox fixtures. No order, key or catalog change is made. |
challenge | valid, invalid_signature, stale_timestamp, duplicate, previous_secret_only | Turns the delivery into a receiver test (below). Omit it for a normal delivery. |
For example {"eventType": "order.fulfilled", "challenge": "invalid_signature"}. Unknown fields
and unknown event names answer 422 VALIDATION_FAILED. Production keys can send test.ping
only: any other eventType, or any challenge, answers 422 SANDBOX_KEY_REQUIRED.
challenge | What Avrix sends | What your endpoint must do |
|---|---|---|
valid | A normally signed delivery | Accept it (2xx) |
invalid_signature | A delivery signed with a random secret | Reject it (non-2xx) |
stale_timestamp | A correctly signed delivery whose signature timestamp is ten minutes old | Reject it (non-2xx) |
duplicate | One delivery sent twice in a row with the same eventId | Accept both and apply it once |
previous_secret_only | A delivery signed with the previous secret only, during a rotation overlap | Accept it |
The 202 response names the queued delivery (deliveryId, deliveryIds), its eventId,
eventType, challenge and testRunId. The delivery body is the usual flat envelope plus a
top-level testEvent object: {"testRunId": "...", "challenge": "invalid_signature"}. Sample ids
in the payload are derived from testRunId, and payloads never contain key plaintext.
Signature challenges (invalid_signature, stale_timestamp, previous_secret_only) get a single
attempt: a refusal is the expected outcome, so they are not retried and never count towards the
auto-disable threshold. previous_secret_only needs an open rotation overlap; without a previous
secret the delivery fails with lastError: no_previous_secret and nothing is sent. A duplicate
delivery retries like any other.
The outcomes feed the webhook cases of the certification report (GET /sandbox/certification).
A 2xx alone never proves that you verify signatures: the report marks a mis-signed delivery
answered 2xx as failed, and a refused one as needing your evidence that it was refused for the
signature. See Certification.
Local development#
Avrix delivers only to public HTTPS URLs, so http://localhost cannot be registered, on sandbox
keys too: a delivery service that reached private addresses could be pointed at anyone's internal
network. Three ways to develop a receiver on your machine:
- Test sends.
POST /webhooks/{id}/testwith a sandbox key sends any event type as a signed sample (see Testing), to whatever public URL the endpoint has. - A tunnel. Run any HTTPS tunnel that gives your local port a public URL, register that URL with a sandbox key, and receive real deliveries. Use a separate endpoint for it and delete it when you are done.
- The local forwarder.
@avrix/seller-api-helpersreads your event log (GET /events, contract date2026-12-01) and posts each event to a local URL with the headers and body a delivery has, signed with a secret you choose. Nothing has to reach your machine from outside.
import { forwardEventsToLocal } from "@avrix/seller-api-helpers/local-forwarder";
let cursor: string | null = null;
for (;;) {
const page = await forwardEventsToLocal({
baseUrl: "https://api.avrix.io",
apiKey: process.env.AVRIX_API_KEY!, // a sandbox key
targetUrl: process.env.LOCAL_WEBHOOK_URL!, // your receiver on this machine
signingSecret: "whsec_local_development_only",
cursor,
});
cursor = page.cursor;
if (!page.hasMore) await new Promise((r) => setTimeout(r, 5000));
}
Point your receiver's verification at the local secret while developing, never at a real endpoint
secret. A forwarded body has eventId equal to eventLogId, since there is no delivery row behind
it, and carries the header X-Avrix-Local-Forward: 1.
Recovering missed events#
Webhooks are a notification channel, not a system of record. If the endpoint was disabled, new events were buffered (up to 10,000 per endpoint) and flush automatically when you re-enable it; events beyond the cap were dropped and must be recovered by polling. If it was up but failing, failed delivery rows may still be retryable or replayable within the operational window above.
| Recovery | Use |
|---|---|
| Re-enable | POST /api/seller/v1/webhooks/{id}/enable before retry/replay (replay answers 409 while the endpoint is not active) |
| Retry one delivery | POST /api/seller/v1/webhooks/{id}/deliveries/{deliveryId}/retry |
| Replay deliveries | POST /api/seller/v1/webhooks/{id}/deliveries/replay or the Console. Replays carry a fresh eventId and the original eventLogId. |
| Read the event log | GET /api/seller/v1/events on contract date 2026-12-01 and later: every event of the last 30 days, including events no endpoint subscribed to. Resume from your stored meta.headCursor. meta.positionBeforeRetention: true means your position is older than the 30 days kept (meta.retainedFrom): events in between may be gone, so reconcile from the resources before continuing |
| Poll orders | GET /api/seller/v1/orders?from=…&to=…&status=…&cursor=… — page the listing and reconcile (authoritative for order state); ?orderReference=… for a single order |
| Poll catalog | GET /api/seller/v1/catalog/changes?since=… |
| Poll allocations | GET /api/seller/v1/allocations |
Run a reconciliation job regardless of webhook health. Compare your order records against
GET /orders on a schedule. Webhook-only architectures fail silently, and the first symptom is a
customer who paid and received nothing.
Event reference#
All 79 event types; GET /webhooks/event-types returns the same list. Subscribe only to what you
handle. New event types are never added to an existing endpoint's subscription: an endpoint
receives only the names in its events.
Orders#
| Event | Fires when |
|---|---|
order.fulfilled | Order completed; entitlements available |
order.failed | Order could not be fulfilled after commit |
order.activated | First successful keyless buyer activation |
order.reserved | Preorder or reservation placed; keys not yet delivered |
order.ready | Deferred preorder or backorder has inventory and can be fulfilled |
order.backorder_expired | A backorder was still awaiting stock at backorderExpiresAt (default 14 days) and was cancelled — refund the buyer |
order.preorder_fulfilled | A key-locked pre-order (bulk line) was delivered at release; read the keys with POST /orders/recover-keys. Also sent, deprecated, beside order.fulfilled when you fulfil a pre-order yourself. Carries no keys |
order.cancelled | You cancelled a pre-order, reservation or backorder before delivery (POST /orders/cancel). It is not a key return: that is order.keys_returned |
order.returned | Older name of order.cancelled, still delivered to endpoints that subscribe to it, with the same eventLogId. Subscribe to order.cancelled instead |
order.keys_returned | Keys quarantined after return — never recycled into sellable inventory without operator review |
return.decided | The Content Owner approved or rejected a key return request you filed |
return.information_requested | The Content Owner needs more information about a key return request you filed |
Refunds#
| Event | Fires when |
|---|---|
refund.completed | POST /refunds or POST /keys/return recorded a refund; carries your reference and the refund ids |
chargeback.opened | POST /refunds with type: "chargeback" recorded a chargeback; report the outcome with POST /chargebacks/resolve |
chargeback.resolved | A chargeback dispute was resolved as won or lost via POST /chargebacks/resolve |
Keys#
| Event | Fires when |
|---|---|
allocation.replenished | Your top-up threshold (replenishThreshold) was crossed and the Content Owner's rules topped the allocation up |
keys.pulled | Keys pulled via POST /keys/pull (non-order path) |
keys.revoked | The Content Owner revoked keys already sold on one of your orders; recommendedAction is replace or refund |
fulfillment.revoked | A keyless redemption link was revoked before redemption (manual, refund, chargeback or a revoked key) |
key.frozen | You froze delivered keys for an open dispute (POST /disputes/freeze) |
key.unfrozen | A dispute freeze ended — released, expired, or settled by a refund or chargeback |
key.replaced | A delivered key was replaced by a fresh one from the same allocation (POST /orders/{orderId}/keys/{keyId}/replace) — no new sale |
key.replacement_rejected | The Content Owner rejected a key replacement you requested; the original key stays delivered |
redemption.expiring | A keyless redemption URL enters its ~24h expiry notice window — nudge the buyer |
redemption.expired | A keyless redemption URL has passed expiresAt without activation |
Allocations#
| Event | Fires when |
|---|---|
allocation.updated | Capacity or metadata changed |
allocation.depleted | Allocation reached zero remaining |
allocation.low_stock | An allocation update left remaining at or below 10% of quantityLimit, and above zero. The 10% is fixed, and the event is sent with every update while that holds; threshold states the number |
allocation.running_low | remaining fell to or below the allocation's low-stock threshold: your replenishThreshold when set, otherwise 10% of quantityLimit. Sent once per crossing, and again only after remaining has risen above the threshold |
allocation.request_decided | An allocation request you filed was approved or denied by the Content Owner, or granted automatically by its rules |
allocation.request_cancelled | A pending allocation request was withdrawn by your company (API or console) before the Content Owner decided it |
Catalog#
| Event | Fires when |
|---|---|
product.added | A product entered your catalog: an agreement or a share now lets you sell it |
product.updated | Product metadata changed — use for incremental sync |
product.announced | Release advanced to announced |
product.delisted | Product removed from your catalog (tombstone) |
product.delisting_scheduled | Product will leave the catalog at a future effectiveAt (only when archived_at is in the future) |
release.available | Release advanced to available |
release.date_changed | Publisher moved a release date (pre-order slip signal) |
sku.pricing_updated | Territory catalog list price changed |
sku.sellability_changed | A shared SKU crossed the sellable boundary, or a SKU you can sell appeared (firstSeen: true) — Buy-button signal |
promotion.offered | A vendor offered you a promotion (a platform event share or a custom deal); answer before respondBy |
promotion.changed | The vendor changed an offered promotion's products or discounts; answerAgain: true means your acceptance was reset |
promotion.accepted | Your company accepted a promotion, over the API or in the console |
promotion.declined | Your company declined a promotion, over the API or in the console |
promotion.withdrawn | The vendor withdrew an offered or accepted promotion; its discounts stop at once |
promotion.expired | A promotion offered to you was not answered by respondBy |
promotion.started | An accepted promotion's window opened; its discounted prices apply from now |
promotion.ended | An accepted promotion's window closed; prices are back to normal |
Contracts#
| Event | Fires when |
|---|---|
contract.activated | BMA or MCA became active |
contract.superseded | Prior active contract term superseded |
contract.amendment_accepted | Amendment accepted by the counterparty |
contract.expiring | An agreement term ends soon (about 30, 14 and 7 days ahead) and has not been renewed |
contract.expired | An agreement term passed its end date without renewal |
contract.terminated | An agreement term ended at the close of its notice period |
connection.suspended | The Content Owner suspended your connection |
connection.reactivated | A suspended connection was reactivated |
connection.ended | Your connection with a Content Owner was closed |
connection.request_decided | A Content Owner approved or rejected a connection request you sent; an approval carries the new connectionId |
access.proposal_created | A Content Owner proposed more countries or a currency; answer with POST /access/proposals/{id}/accept or /decline |
Finance and system#
| Event | Fires when |
|---|---|
invoice.created | Pro-forma invoice of an allocation created |
invoice.issued | A Content Owner issued a monthly invoice to you |
invoice.overdue | A monthly invoice passed its due date unpaid; it stays payable |
invoice.disputed | You disputed a monthly invoice; payment is paused until the Content Owner answers |
invoice.dispute_updated | The Content Owner answered your dispute, or you withdrew it; outcome says how |
invoice.paid | Your payment of a monthly invoice was recorded |
report.ready | A monthly sales report is ready; read it with GET /finance/reports/{reportId} |
payout.file_ready | A payout settled and its reconciliation file is final — download GET /finance/invoices/{invoiceId}/reconciliation |
catalog.export_ready | An async catalog export artifact is ready — poll GET /catalog/exports/{exportId} |
test.ping | You called POST /webhooks/{id}/test (sandbox keys can also send any other event as a testEvent) |
system.webhook_endpoint_disabled | The circuit breaker auto-disabled one of your endpoints (delivered to your other endpoints) |
system.webhook_endpoint_failing | Deliveries to one of your endpoints have failed for a while; it is still active (also on your event log) |
system.webhook_endpoint_recovered | A failing endpoint answered 2xx again |
platform.notice | Avrix announces a change to the Seller API: a contract change, a deprecation, a default contract date change, rate-limit enforcement or planned maintenance. Sent only to endpoints that subscribe to it |
api_key.created | An API key was created for your company, in the console or with POST /keys |
api_key.rotated | An API key's secret was replaced; the key id stays the same |
api_key.revoked | An API key was revoked |
api_key.expiring | An API key expires within 14 days; replace it before then |
api_key.expired | An API key reached its expiry and no longer authenticates |
sandbox.certification_passed | A sandbox key's certification report passed every case: the first time, or again after a failed report |
Per-event payload schemas live in the OpenAPI webhooks section
(GET /api/seller/v1/openapi on your API host).
Worked examples and seller-action notes for each event are in Event reference.
Checklist#
- Signature verified on every delivery, using the raw body
- Constant-time comparison
- Timestamp tolerance enforced at 300 seconds
- Multiple
v1=values handled for rotation - Deduplication on
eventLogId(X-Avrix-Event-Log-Id) - Event id and effect committed in one transaction
-
2xxreturned within the 8-second delivery timeout; work done asynchronously - Handler tolerates an order it has not yet recorded
- Handler tolerates out-of-order events
- Corrupted-signature rejection tested
- Reconciliation job running independently of webhooks
- Secret in a managed secret store
- Delivery-failure alerting in place (Avrix warns early with
system.webhook_endpoint_failingand the console, and on circuit open viasystem.webhook_endpoint_disabled, console, and email — but watch your own receiver too) - Know how to
disable,enable(withreplayFrom),retry, andreplayaround an outage
Related#
- Order lifecycle — which transition emits which event
- Catalog and allocations — event-driven catalog refresh
- Idempotency — write retries and
orderReferencerecovery - Rate limits — webhooks management class
- Error reference — every error code