Webhooks

Get notified when an order changes so your systems can fetch the latest state instead of polling.

Printeers offers a single webhook today, the order-updated notification. It was introduced alongside the V1 API, but it is not tied to the V1 lifecycle: it keeps working for orders created through V2 and stays available after V1 is retired. A broader webhook system covering more event types is on our roadmap, currently estimated for Q4 2026 / Q1 2027.

What the webhook does

Whenever one of your orders is shipped, Printeers calls a URL you configured. The notification tells you that an order changed, not what changed. The payload deliberately carries no order details; you respond by fetching the current state from the API using one of the GET order endpoints.

This keeps you in sync without polling: you react to a notification, fetch the order, and read its current status, shipment information, tracking, and so on.

Configuring your callback URL

Set the callback URL per store in the Printeers dashboard, under the store's settings, in the API Callback URL field. Each store can have its own URL. Leave it empty to disable notifications for that store.

How a notification is delivered

When an order changes, Printeers sends an HTTP GET request to your callback URL. There is no request body; all information travels in query parameters:

GET https://yourwebsite.com/printeers-order-update?environment=prod&order_reference=YOURCODE-42&order_reference_v2=Order_5x4rwj6knrhks8m19s8j6nc4z8&custom_reference=yourCustomOrderRef&store_code=YOURCODE

Parameter	Always present	Description
`environment`	yes	`prod` or `test`, so you can route the call to the right system.
`order_reference`	yes	The order's V1-style reference, `<store_code>-<number>` (e.g. `YOURCODE-42`).
`order_reference_v2`	yes	The order's V2 reference (e.g. `Order_5x4rwj6knrhks8m19s8j6nc4z8`). Pass it straight to the V2 `GET /orders/{orderReference}` endpoint.
`store_code`	yes	The store the order belongs to.
`custom_reference`	when set	The custom identifier you supplied when creating the order.
`via_store_code`	when applicable	The integrator code, if the order was created through an integrator.

Any query parameters already present on the URL you configured are preserved and merged in. If one of your own parameters collides with a Printeers parameter name, the Printeers value wins.

Deprecated parameter aliases

For backwards compatibility the request also includes the older names partner_reference (alias of custom_reference), partner_code (alias of store_code), and via_partner_code (alias of via_store_code). These have been deprecated since 2022 and may be removed. Read the current names listed above instead.

Responding to a notification

Return an HTTP 2xx status (a plain 200 is ideal) to acknowledge receipt. Do this as soon as you have safely recorded the notification; do the actual order fetch afterwards, out of band.

If your endpoint returns any non-2xx status, is unreachable, or times out, Printeers postpones the notification and retries it about 5 minutes later. Retries continue until the call succeeds, so a brief outage on your side will not lose a notification, but a permanently broken endpoint will keep being retried. Repeated failures raise an internal alert at Printeers.

Because retries and the occasional overlap of updates mean you may receive more than one notification for the same order, treat notifications as idempotent: always fetch the current order state rather than assuming a particular transition happened.

Fetching the order after a notification

Use the version of the API your integration is built on:

V1: call GET /orders/{reference} with the order_reference from the query string.
V2: call GET /orders/{orderReference} with the order_reference_v2 from the query string. You can also correlate on your own custom_reference if you stored the order under your own identifier. See V1 vs V2 for how references map between versions.