# Webhooks (legacy)

Canonical URL: https://api-docs.test-printeers.com/guides/legacy-webhooks

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

> **This is the legacy webhook notification guide.** It documents the original single-purpose **order-updated** callback. Printeers now has a full webhook system with multiple event types, signed deliveries, and a delivery log; see the [Webhooks](https://api-docs.test-printeers.com/guides/webhooks.md) guide. Existing order-updated callbacks keep working, but new integrations should use the webhook system.

The order-updated notification 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.

## 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}`](https://api-docs.test-printeers.com/reference/v2#tag/orders/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}`](https://api-docs.test-printeers.com/reference/v1#tag/orders/GET/orders/{reference}) with the `order_reference` from the query string.
- **V2**: call [`GET /orders/{orderReference}`](https://api-docs.test-printeers.com/reference/v2#tag/orders/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](https://api-docs.test-printeers.com/guides/v1-vs-v2.md) for how references map between versions.