Webhooks

Signed delivery, event types, retries, and verification.

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#

Diagram

If you implement only one thing from this page, implement signature verification.

Registering an endpoint#

Bash
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"]
  }'
JSON
{
  "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:

HeaderPurpose
X-Avrix-SignatureHMAC-SHA256 in the form t=<unix-seconds>,v1=<hex>
X-Avrix-Signature-VersionCurrently 1
X-Avrix-Event-VersionPayload schema version, currently 1
X-Avrix-Event-Log-IdThe 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-IdId 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-IdThe delivery row, as GET /webhooks/{id}/deliveries lists it; quote it when you report a delivery problem
X-Avrix-Event-TypeEvent name, matching your subscription
User-AgentAvrix-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:

JSON
{
  "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:

  1. 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.
  2. Compare in constant time. A naive == leaks timing information.
  3. 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 webhook

Spring (Java)#

# Inbound webhook

ASP.NET (C#)#

# Inbound webhook

Express handler with a raw body (TypeScript):

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:

AttemptDelay after previous
1immediate
230 seconds
32 minutes
410 minutes
51 hour
62 hours
76 hours
812 hours
924 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:

  1. records system.webhook_endpoint_failing on your event log, so GET /events (contract date 2026-12-01 and later) has it even when every endpoint you have is down;
  2. delivers the same event to your endpoints that subscribe to it;
  3. 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:

Bash
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 a since/until window of at most 7 days and up to 1,000 source deliveries per call (default limit 200). When the window holds more than limit, the response says hasMore: true and gives nextSince: call again with since set to it to replay the rest. Deliveries created at that exact instant are matched again by the next call.
  • Send an Idempotency-Key with 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-01 and 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-Id and the SAME X-Avrix-Event-Log-Id. It is a new delivery of the same event. Deduplicating on eventLogId, as recommended above, makes replay idempotent: a replayed event you already applied is recognised. If you deduplicate on eventId, 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 replay object with replay.originalEventId (the eventId of the original delivery) and replay.sourceDeliveryId (the original delivery row). For deliveries without an eventLogId, event.replay?.originalEventId ?? event.eventId is 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 (succeeded or failed) 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, with attemptedAt, outcome, responseStatus, responseBodyExcerpt, error and durationMs.

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#

MethodPathPurpose
GET/api/seller/v1/webhooks/{id}One endpoint: subscription, status, delivery health and queue
POST/api/seller/v1/webhooks/{id}/disablePause an endpoint; events are buffered until you enable it
POST/api/seller/v1/webhooks/{id}/enableRe-enable after circuit-breaker or manual disable (clears failure streak); replayFrom skips older buffered events
POST/api/seller/v1/webhooks/{id}/deliveries/{deliveryId}/retryRe-queue a failed delivery (fresh attempt cycle); returns 202
GET/api/seller/v1/webhooks/event-typesCatalog of event names and short descriptions for subscription discovery
GET/api/seller/v1/webhooks/{id}/deliveriesDelivery 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/replayBulk clone deliveries in a time window (fresh eventId; correlate via the top-level replay object)
POST/api/seller/v1/webhooks/{id}/testSigned 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/eventsYour 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 pinned is 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 pinned is 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 (413 PAYLOAD_TOO_LARGE when exceeded).
  • Each endpoint’s events array 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-01 and 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 /events recover 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.

TypeScript
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#

Bash
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:

Bash
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 eventId is 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:

FieldValuesEffect
eventTypeAny 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.
challengevalid, invalid_signature, stale_timestamp, duplicate, previous_secret_onlyTurns 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.

challengeWhat Avrix sendsWhat your endpoint must do
validA normally signed deliveryAccept it (2xx)
invalid_signatureA delivery signed with a random secretReject it (non-2xx)
stale_timestampA correctly signed delivery whose signature timestamp is ten minutes oldReject it (non-2xx)
duplicateOne delivery sent twice in a row with the same eventIdAccept both and apply it once
previous_secret_onlyA delivery signed with the previous secret only, during a rotation overlapAccept 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:

  1. Test sends. POST /webhooks/{id}/test with a sandbox key sends any event type as a signed sample (see Testing), to whatever public URL the endpoint has.
  2. 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.
  3. The local forwarder. @avrix/seller-api-helpers reads your event log (GET /events, contract date 2026-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.
TypeScript
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.

RecoveryUse
Re-enablePOST /api/seller/v1/webhooks/{id}/enable before retry/replay (replay answers 409 while the endpoint is not active)
Retry one deliveryPOST /api/seller/v1/webhooks/{id}/deliveries/{deliveryId}/retry
Replay deliveriesPOST /api/seller/v1/webhooks/{id}/deliveries/replay or the Console. Replays carry a fresh eventId and the original eventLogId.
Read the event logGET /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 ordersGET /api/seller/v1/orders?from=…&to=…&status=…&cursor=… — page the listing and reconcile (authoritative for order state); ?orderReference=… for a single order
Poll catalogGET /api/seller/v1/catalog/changes?since=…
Poll allocationsGET /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#

EventFires when
order.fulfilledOrder completed; entitlements available
order.failedOrder could not be fulfilled after commit
order.activatedFirst successful keyless buyer activation
order.reservedPreorder or reservation placed; keys not yet delivered
order.readyDeferred preorder or backorder has inventory and can be fulfilled
order.backorder_expiredA backorder was still awaiting stock at backorderExpiresAt (default 14 days) and was cancelled — refund the buyer
order.preorder_fulfilledA 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.cancelledYou cancelled a pre-order, reservation or backorder before delivery (POST /orders/cancel). It is not a key return: that is order.keys_returned
order.returnedOlder name of order.cancelled, still delivered to endpoints that subscribe to it, with the same eventLogId. Subscribe to order.cancelled instead
order.keys_returnedKeys quarantined after return — never recycled into sellable inventory without operator review
return.decidedThe Content Owner approved or rejected a key return request you filed
return.information_requestedThe Content Owner needs more information about a key return request you filed

Refunds#

EventFires when
refund.completedPOST /refunds or POST /keys/return recorded a refund; carries your reference and the refund ids
chargeback.openedPOST /refunds with type: "chargeback" recorded a chargeback; report the outcome with POST /chargebacks/resolve
chargeback.resolvedA chargeback dispute was resolved as won or lost via POST /chargebacks/resolve

Keys#

EventFires when
allocation.replenishedYour top-up threshold (replenishThreshold) was crossed and the Content Owner's rules topped the allocation up
keys.pulledKeys pulled via POST /keys/pull (non-order path)
keys.revokedThe Content Owner revoked keys already sold on one of your orders; recommendedAction is replace or refund
fulfillment.revokedA keyless redemption link was revoked before redemption (manual, refund, chargeback or a revoked key)
key.frozenYou froze delivered keys for an open dispute (POST /disputes/freeze)
key.unfrozenA dispute freeze ended — released, expired, or settled by a refund or chargeback
key.replacedA delivered key was replaced by a fresh one from the same allocation (POST /orders/{orderId}/keys/{keyId}/replace) — no new sale
key.replacement_rejectedThe Content Owner rejected a key replacement you requested; the original key stays delivered
redemption.expiringA keyless redemption URL enters its ~24h expiry notice window — nudge the buyer
redemption.expiredA keyless redemption URL has passed expiresAt without activation

Allocations#

EventFires when
allocation.updatedCapacity or metadata changed
allocation.depletedAllocation reached zero remaining
allocation.low_stockAn 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_lowremaining 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_decidedAn allocation request you filed was approved or denied by the Content Owner, or granted automatically by its rules
allocation.request_cancelledA pending allocation request was withdrawn by your company (API or console) before the Content Owner decided it

Catalog#

EventFires when
product.addedA product entered your catalog: an agreement or a share now lets you sell it
product.updatedProduct metadata changed — use for incremental sync
product.announcedRelease advanced to announced
product.delistedProduct removed from your catalog (tombstone)
product.delisting_scheduledProduct will leave the catalog at a future effectiveAt (only when archived_at is in the future)
release.availableRelease advanced to available
release.date_changedPublisher moved a release date (pre-order slip signal)
sku.pricing_updatedTerritory catalog list price changed
sku.sellability_changedA shared SKU crossed the sellable boundary, or a SKU you can sell appeared (firstSeen: true) — Buy-button signal
promotion.offeredA vendor offered you a promotion (a platform event share or a custom deal); answer before respondBy
promotion.changedThe vendor changed an offered promotion's products or discounts; answerAgain: true means your acceptance was reset
promotion.acceptedYour company accepted a promotion, over the API or in the console
promotion.declinedYour company declined a promotion, over the API or in the console
promotion.withdrawnThe vendor withdrew an offered or accepted promotion; its discounts stop at once
promotion.expiredA promotion offered to you was not answered by respondBy
promotion.startedAn accepted promotion's window opened; its discounted prices apply from now
promotion.endedAn accepted promotion's window closed; prices are back to normal

Contracts#

EventFires when
contract.activatedBMA or MCA became active
contract.supersededPrior active contract term superseded
contract.amendment_acceptedAmendment accepted by the counterparty
contract.expiringAn agreement term ends soon (about 30, 14 and 7 days ahead) and has not been renewed
contract.expiredAn agreement term passed its end date without renewal
contract.terminatedAn agreement term ended at the close of its notice period
connection.suspendedThe Content Owner suspended your connection
connection.reactivatedA suspended connection was reactivated
connection.endedYour connection with a Content Owner was closed
connection.request_decidedA Content Owner approved or rejected a connection request you sent; an approval carries the new connectionId
access.proposal_createdA Content Owner proposed more countries or a currency; answer with POST /access/proposals/{id}/accept or /decline

Finance and system#

EventFires when
invoice.createdPro-forma invoice of an allocation created
invoice.issuedA Content Owner issued a monthly invoice to you
invoice.overdueA monthly invoice passed its due date unpaid; it stays payable
invoice.disputedYou disputed a monthly invoice; payment is paused until the Content Owner answers
invoice.dispute_updatedThe Content Owner answered your dispute, or you withdrew it; outcome says how
invoice.paidYour payment of a monthly invoice was recorded
report.readyA monthly sales report is ready; read it with GET /finance/reports/{reportId}
payout.file_readyA payout settled and its reconciliation file is final — download GET /finance/invoices/{invoiceId}/reconciliation
catalog.export_readyAn async catalog export artifact is ready — poll GET /catalog/exports/{exportId}
test.pingYou called POST /webhooks/{id}/test (sandbox keys can also send any other event as a testEvent)
system.webhook_endpoint_disabledThe circuit breaker auto-disabled one of your endpoints (delivered to your other endpoints)
system.webhook_endpoint_failingDeliveries to one of your endpoints have failed for a while; it is still active (also on your event log)
system.webhook_endpoint_recoveredA failing endpoint answered 2xx again
platform.noticeAvrix 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.createdAn API key was created for your company, in the console or with POST /keys
api_key.rotatedAn API key's secret was replaced; the key id stays the same
api_key.revokedAn API key was revoked
api_key.expiringAn API key expires within 14 days; replace it before then
api_key.expiredAn API key reached its expiry and no longer authenticates
sandbox.certification_passedA 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
  • 2xx returned 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_failing and the console, and on circuit open via system.webhook_endpoint_disabled, console, and email — but watch your own receiver too)
  • Know how to disable, enable (with replayFrom), retry, and replay around an outage

What links here

Published guides that link to this page.

Search docs

Search documentation…