Webhooks
A webhook lets OrderEx call your system when an order is created or changes, so you do not have to ask. This guide shows how to register one, what OrderEx sends, how to check that a call comes from OrderEx, and how retries work.
The events
| Event type | Sent when |
|---|---|
order.created | An order is created |
order.line_added | A line is added to an order |
order.metadata_changed | An order's metadata changes |
order.status_changed | An order moves to another status |
Facts such as cancellations, shipments, tracking events, returns and payment facts are not sent as webhooks. Read them from the order, its shipments and its timeline, as Reading data shows.
What you do
1. Register your address
curl -sS -X POST "https://api.orderex.se/api/v1/webhooks" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/orderex",
"eventTypes": ["order.created", "order.status_changed"],
"description": "Order updates to the example shop"
}'
url is an absolute HTTPS or HTTP address of at most 2048 characters. Use HTTPS. eventTypes names
at least one of the four events.
2. Store the secret
The 201 Created response holds the webhook's id and its secret. This is the only time OrderEx
shows the secret: no other call returns it. Store it in your secret store, beside the code that
receives the calls.
3. Receive the calls
OrderEx sends each event as a POST to your address, with a JSON body and these headers:
| Header | What it holds |
|---|---|
Content-Type | application/json |
User-Agent | OrderEx-Webhooks/1.0 |
X-OrderEx-Signature | sha256= followed by the signature of the body, see below |
X-OrderEx-Event-Id | The event's id, the same as id in the body |
X-OrderEx-Event-Type | The event type, the same as type in the body |
The body has the event's id, its type, occurred_at in UTC and the event's data. A time has up to 7
digits after the decimal point, so parse it with a format that accepts from 0 to 7. Names are in
snake case, and a field without a value is left out. An order.status_changed looks like this, here
indented for reading:
{
"id": "0e1d2c3b-4a59-4687-9a6b-5c4d3e2f1a0b",
"type": "order.status_changed",
"occurred_at": "2026-11-14T10:05:41.3182046Z",
"data": {
"event_id": "0e1d2c3b-4a59-4687-9a6b-5c4d3e2f1a0b",
"event_type": "order.status_changed",
"new_status": "Confirmed",
"occurred_at": "2026-11-14T10:05:41.3182046Z",
"order_id": "5f8a2c1e-3b4d-4e6f-8a9b-1c2d3e4f5a6b",
"previous_status": "Pending"
}
}
Answer with any 2xx status within 30 seconds, and do the work after you have answered. Any other
status, a network error or no answer within 30 seconds counts as a failed attempt.
4. Verify the signature
The signature is an HMAC with SHA-256 of the raw body, as UTF-8 bytes, keyed with the UTF-8 bytes of
the whole secret, written as lowercase hex after sha256=. Compute it over the bytes you received,
before you parse the JSON, and compare it with the header in constant time. Reject a call whose
signature does not match.
An example in Node.js, with the secret in the environment variable ORDEREX_WEBHOOK_SECRET:
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
const secret = process.env.ORDEREX_WEBHOOK_SECRET;
function isFromOrderEx(rawBody, signatureHeader) {
const expected = Buffer.from("sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex"));
const received = Buffer.from(signatureHeader ?? "");
return received.length === expected.length && timingSafeEqual(received, expected);
}
createServer((request, response) => {
const chunks = [];
request.on("data", (chunk) => chunks.push(chunk));
request.on("end", () => {
const rawBody = Buffer.concat(chunks);
if (!isFromOrderEx(rawBody, request.headers["x-orderex-signature"])) {
response.writeHead(401).end();
return;
}
response.writeHead(204).end();
const event = JSON.parse(rawBody.toString("utf8"));
queueForProcessing(request.headers["x-orderex-event-id"], event);
});
}).listen(8080);
queueForProcessing stands for your own code, which handles the event once, as the next section
explains.
Retries and duplicates
OrderEx delivers each event at least once. A delivery is tried up to 7 times. After a failed attempt, the next one waits:
| After attempt | Wait before the next |
|---|---|
| 1 | 30 seconds |
| 2 | 2 minutes |
| 3 | 10 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 8 hours |
Each wait gets up to 25 percent more at random. After the seventh failed attempt OrderEx stops.
So your receiver must:
- Handle duplicates. The same event can arrive more than once. Keep the
X-OrderEx-Event-Idof events you have handled, and skip one you have seen. - Not depend on the order of arrival. An event that was retried can arrive after a newer one.
Use
occurred_at, or read the order withGET /api/v1/orders/{id}when you need its current state. - Answer fast. Answer first and process afterwards, so a slow job does not cost an attempt.
See what was delivered
curl -sS "https://api.orderex.se/api/v1/webhooks/$WEBHOOK_ID/deliveries?page=1&pageSize=20" \
-H "X-Api-Key: $ORDEREX_API_KEY"
Each delivery has its attemptCount, lastResponseStatusCode, lastError and status, newest first.
GET /api/v1/orders/{orderId}/webhook-deliveries lists the deliveries about one order.
| Status | In the per order list | In the per webhook list | Meaning |
|---|---|---|---|
| Pending | Pending | 0 | Not tried yet |
| Delivered | Delivered | 1 | Your system answered with a 2xx |
| Failed | Failed | 2 | An attempt failed, and another will follow |
| Permanently failed | PermanentlyFailed | 3 | All 7 attempts failed. OrderEx does not try again |
Change, pause or remove a webhook
| Call | What it does |
|---|---|
GET /api/v1/webhooks | Lists your webhooks, without their secrets |
PUT /api/v1/webhooks/{webhookId} | Changes url, eventTypes, description or isActive |
DELETE /api/v1/webhooks/{webhookId} | Removes the webhook |
A webhook with isActive: false gets no new events, and each attempt of an earlier delivery that
falls due while it is inactive counts as failed, so that delivery reaches you only if the webhook is
active again before its last attempt.
Rotate the secret
A webhook keeps its secret for as long as it exists. To change the secret, for example when it may have leaked:
- Register a new webhook with the same address and events, and store its secret.
- Let your receiver accept a signature made with either secret. While both webhooks exist, each
event arrives twice with the same
X-OrderEx-Event-Id, so your duplicate check handles it once. - Delete the old webhook with
DELETE /api/v1/webhooks/{webhookId}, and remove the old secret from your receiver.
Next
Going live is the checklist before your integration reaches production.