Handle an Order Placed Event

orders.order.placed tells you that one of your orders has been created and confirmed in our order system. This page walks the whole path: what arrives, what to check, when to answer, and how to turn the notification into the actual order. The same path applies to every other event type — only the reason for the notification differs.

What you receive

POST /webhooks/komplett HTTP/1.1
Host: your-endpoint.example.com
content-type: application/json
webhook-id: 84a4a78bd45d732c5241ee8180896267
webhook-timestamp: 1786001423
webhook-signature: v1,{base64_signature}

{
  "eventId": "84a4a78bd45d732c5241ee8180896267",
  "eventType": "orders.order.placed",
  "occurredAt": "2026-08-06T09:30:23.1945315+02:00",
  "version": 1,
  "entity": { "id": "2004148349", "type": "order" },
  "resource": { "href": "/orders/v1/2004148349", "rel": "order:read" }
}

webhook-id and the payload’s eventId are the same value — either one works as your idempotency key. entity.id is the order number, and webhook-timestamp is occurredAt in Unix seconds.

webhook-signature is shown as {base64_signature} because the real value is derived from your own subscription secret — no signature printed here could match what you receive. Compute it yourself as below rather than testing your verifier against this page.

1. Verify the signature

Before anything else, confirm the delivery is from us. Compute the HMAC over {webhook-id}.{webhook-timestamp}.{raw body} and compare it against webhook-signature, using the raw bytes as received. If it does not match, respond 401 and stop.

Full walkthrough with working code: Verify a signature.

2. Deduplicate on `eventId`

eventId is stable for a given logical event, so a redelivery of the same event carries the identical value. Record the ids you have processed and ignore repeats.

This is not optional. Delivery is at-least-once, and both retries and replays can re-send an event you have already handled. Without a deduplication check, a single order can be booked into your system more than once.

Keep the ids for longer than the retry window — the schedule spans roughly 21 hours, so an id can reappear a day after you first saw it. See Retries and failures.

3. Answer before you do the work

You have 10 seconds. Return a 2xx as soon as the event is safely queued on your side, then process it asynchronously.

Doing the work inline risks a timeout, and a timeout is a failed delivery that we retry — so slow processing turns one event into up to eight deliveries of the same thing, each one arriving while the previous is still being processed.

4. Fetch the order

resource.href is a path, not a URL. Resolve it against your own base:

GET https://<store-url>/public/orders/v1/2004148349
Authorization: Bearer {access_token}
Ocp-Apim-Subscription-Key: {your_subscription_key}

The token needs the order:read scope — the same scope the endpoint always requires; the notification grants nothing by itself. href is already percent-encoded, so append it to the base without re-encoding it.

For the response shape and how to read order state, see Orders overview.

Fetch when you process, not when you receive: the endpoint returns the order’s current state rather than a snapshot from the moment the event fired, so a late fetch gives you a more accurate answer, never a staler one.

Two things that surprise people

This is not a checkout confirmation. The event fires once the order has been created and confirmed in our order system, which happens after your checkout call has already returned. Never block a checkout response waiting for it, and never treat its absence as a failed checkout. For what checkout returns synchronously, see Checkout overview.

Only the SoldTo customer is notified. If you are ShipTo, BillTo, ContactTo or PlacedBy on an order but not SoldTo, no webhook is sent to you for that order — you will need to poll the Orders API for those.

For the other events an order raises, and how they follow one another, see Follow an order lifecycle.