Inventory Webhooks: Real-Time Stock Sync Without the Polling

Inventory webhooks are how your inventory system tells the rest of your stack that something changed, the moment it changes, instead of you asking over and over. A unit sells, a purchase order is received, stock drops below a threshold, and your storefront, accounting, and shipping tools all find out in the same second.
If you are syncing stock across more than one system, this is the difference between "our numbers are always right" and "we oversold again." The sections below cover how inventory webhooks work, how to verify them, and how to handle the parts that bite people in production.
What an inventory webhook actually is
A webhook is an HTTP POST that your inventory system sends to a URL you own. You register an endpoint, subscribe to the events you care about, and from then on the inventory system pushes a small JSON payload to that URL whenever one of those events fires.
That is the whole idea. You are not calling an API. The API is calling you. Your job is to stand up an endpoint that accepts the POST, verifies it is genuine, and does something useful with the payload.
Webhooks vs polling
The alternative to webhooks is polling: hitting GET /products on a timer and diffing the results to spot changes. It works, and it is also wasteful and slow.
| Polling | Webhooks | |
|---|---|---|
| Freshness | Stale up to your poll interval | Near-instant |
| Requests | Thousands of "did anything change?" calls | One call per real event |
| Cost | You pay for empty responses | You pay for signal only |
| Complexity | Simple to start, scales badly | Needs a public endpoint and verification |
| Missed changes | Fine if it lags | Needs retry handling |
Polling a busy catalog every 30 seconds means roughly 2,880 requests a day per endpoint, and the vast majority return "nothing changed." Webhooks flip that: a product with 40 stock movements a day sends 40 calls. You do more work up front to stand up the receiver, and you stop hammering an API for data that has not moved.
Events worth subscribing to
Do not subscribe to everything. A firehose is as useless as no data. Pick the events that map to an action on your side:
stock.adjusted: stock was adjusted (manual, count, damage, return or transfer). The core event for stock sync.product.low_stock: a product fell below its minimum stock. Trigger a purchase order or an alert.purchase_order.received: inbound stock landed. Update what is available to sell.product.updated: name, SKU, price, or other product fields changed. Push to your storefront.product.deleted: pull it from every channel before you sell a ghost.
Inventoros also sends order.* events (order.created, order.status_changed and others, for sales orders), product.out_of_stock, payment, shipment, customer, return, transfer, work order and stock audit events. The full list is in the REST API docs. Subscriptions are per event, not per location, so filter by the IDs in the payload on your side if a tool only cares about one warehouse.
A worked example: verifying a signed webhook
Never trust a webhook because it hit your URL. Anyone who learns the URL can POST to it. The fix is a signature. The inventory system signs each payload with a shared secret, sends the signature in a header, and you recompute it to confirm the call is real and untampered.
Every Inventoros delivery wraps the event data in the same envelope. This is a product.low_stock delivery with example values:
{
"id": "wh_k3Jf9aQ2xLm8RtZ0pWc4VnBd",
"event": "product.low_stock",
"timestamp": "2026-07-04T14:03:11+00:00",
"organization_id": 1,
"data": {
"product": {
"product": {
"id": 412,
"name": "Example phone case",
"sku": "CASE-IP15-BLK",
"stock": 240,
"min_stock": 250,
"is_active": true
}
},
"current_stock": 240,
"min_stock": 250
}
}
The payload also carries price, category and timestamp fields, trimmed here. The nested product.product is how the current payload formats a product inside data.
Each request carries three headers: X-Webhook-Signature, X-Webhook-Event (the event name) and X-Webhook-Delivery (the delivery ID). The signature is the HMAC-SHA256 of the raw request body, keyed with the webhook's secret and written as a bare hex string, with no sha256= prefix. To verify it in Node:
import crypto from "node:crypto";
function verify(rawBody, signatureHeader, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
const a = Buffer.from(signatureHeader ?? "", "utf8");
const b = Buffer.from(expected, "utf8");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Here rawBody is the unparsed request body (a Buffer or string), and signatureHeader is the value of X-Webhook-Signature.
Two rules that matter here. First, hash the raw request body, not a re-serialized object, because reordered keys or different whitespace change the hash. Second, use a constant-time compare (timingSafeEqual), not ===, so you do not leak the secret through timing. If verification fails, return 401 and stop. Do not process the payload.
How to set up inventory webhooks
The flow is the same across most systems:
- Stand up an endpoint. A single POST route, publicly reachable over HTTPS. It reads the body, verifies the signature, and returns fast.
- Register it. Point the inventory system at the URL and store the signing secret somewhere safe, not in your repo.
- Subscribe to events. Pick the handful you will actually act on.
- Verify, then queue. Confirm the signature, push the job onto a queue, and return
200immediately. Do the slow work (calling other APIs, writing to channels) in a background worker. - Test with a replay. Fire a test event and watch it flow end to end before you rely on it.
Returning 200 fast matters. Inventoros treats any non-2xx response as a failed attempt and retries it, which brings us to the part everyone underestimates.
Retries and idempotency
Networks blink. Your app deploys. A webhook will occasionally fail to reach you, so any sender worth using retries with backoff. Inventoros makes up to 5 tries per delivery, waiting 1 minute, 5 minutes, 30 minutes, 2 hours and 24 hours between them by default. Retries make delivery reliable, and they also mean you will sometimes get the same event twice.
If receiving purchase_order.received twice adds the stock twice, your counts are now wrong and you did it to yourself. The fix is idempotency: treat each envelope id as a key you process exactly once. A retry resends the same payload, so the id is stable across attempts.
if (await seen(event.id)) return res.sendStatus(200);
await process(event);
await markSeen(event.id);
Store processed ids for a rolling window (a day is plenty for most retry schedules) and short-circuit duplicates with a 200 so the sender stops retrying. Design every handler to be safe to run twice. That single habit removes a whole category of "the numbers drifted and nobody knows why" bugs.
Where Inventoros fits
Inventoros ships signed, retrying inventory webhooks in the open-source core, alongside a REST API that covers every resource, a GraphQL API for the core data, and an MCP server for AI assistants. Because you self-host it, the webhook endpoints live on your own infrastructure next to the systems they sync with, and there is no per-call pricing to plan around.
You register endpoints under Settings > Webhooks or with POST /api/v1/webhooks. The signing secret is shown only when you create the webhook or regenerate it, so store it then. GET on the webhook's deliveries endpoint lists past deliveries and their status. Delivery goes only to public HTTP or HTTPS addresses, and redirects are not followed. The REST API docs list every event.
FAQ
What is the difference between an inventory webhook and an inventory API? The API is something you call to read or change data. A webhook is the inventory system calling you when data changes. You use the API for on-demand reads and writes, and webhooks for real-time notifications so you are not polling the API to spot changes.
How do I secure an inventory webhook endpoint? Serve it over HTTPS, verify the signature on every request using the shared secret and a constant-time compare, and reject anything that fails. Optionally restrict inbound IPs and rate-limit the route. Never act on an unsigned or unverified payload.
What happens if my endpoint is down when an event fires? A good sender retries with backoff, so a short outage means delivery is delayed, not lost. Inventoros retries up to 5 times over roughly a day. This is exactly why your handlers must be idempotent: retries can deliver the same event more than once, and processing it twice should never corrupt your stock counts.
Do I need webhooks if I already poll the API? If real-time accuracy matters, yes. Polling is stale between intervals and burns requests on empty responses. Webhooks push only real changes the instant they happen, which is what keeps stock levels correct across multiple sales channels.