Skip to main content

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 typeSent when
order.createdAn order is created
order.line_addedA line is added to an order
order.metadata_changedAn order's metadata changes
order.status_changedAn 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:

HeaderWhat it holds
Content-Typeapplication/json
User-AgentOrderEx-Webhooks/1.0
X-OrderEx-Signaturesha256= followed by the signature of the body, see below
X-OrderEx-Event-IdThe event's id, the same as id in the body
X-OrderEx-Event-TypeThe 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 attemptWait before the next
130 seconds
22 minutes
310 minutes
430 minutes
52 hours
68 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-Id of 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 with GET /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.

StatusIn the per order listIn the per webhook listMeaning
PendingPending0Not tried yet
DeliveredDelivered1Your system answered with a 2xx
FailedFailed2An attempt failed, and another will follow
Permanently failedPermanentlyFailed3All 7 attempts failed. OrderEx does not try again

Change, pause or remove a webhook​

CallWhat it does
GET /api/v1/webhooksLists 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:

  1. Register a new webhook with the same address and events, and store its secret.
  2. 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.
  3. 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.