# Push API Sales Webhooks OpenAPI file: https://push-api.doc.winkelstraat.nl/source.json ## Description This is version `2.1.0` of this API documentation. Last update on Jul 21, 2026. # Push API — Sales Webhooks Winkelstraat.nl sends **webhooks** to keep merchants updated during order fulfilment. A webhook is an automatic message: whenever something important happens to an order — a shipment is created, a tracking label is ready, a return (RMA) comes in, or an item is refunded — Winkelstraat.nl sends a small JSON message (an HTTP POST) to a URL you provide. You don't have to ask us for updates; we push them to you in real time. This documentation is organised per topic: **Shipment**, **Track**, **RMA**, and **Order Item**. Each webhook explains what it is for, when it is sent, and which fields it contains. ## Which version should I use? (V1 vs V2) **Use V2. V1 is deprecated** and only kept available for existing integrations. - **V2** is the recommended, actively maintained version. New integrations should always use V2. - **V1** still works but receives no new features and may be removed in the future. V1 webhooks are marked *deprecated* throughout this documentation. What changed in V2: - A dedicated **RMA** webhook was added (V1 only had RMA *item* updates), giving a clearer view of the whole return. - Field names were made clearer and consistent — e.g. V1's `uid` → `shipment_token`, `id` → `shipment_id`, `main_order_id` → `order_id`. Every V1 webhook description names its V2 replacement. ## Test vs Live environment Winkelstraat.nl provides two environments: - **Test / staging** — build and validate your integration without affecting real orders. Base URL: `https://staging-magento2.winkelstraat.nl`. - **Live (production)** — real orders and real customers. Base URL: `https://checkout.winkelstraat.nl`. Both environments send the same webhook payloads and use the same authentication (a per-merchant `x-api-key`; see *Authentication*). Your endpoint URLs and API key are configured **per environment**, so validate your integration on staging before switching to live. ## How to test your integration You don't have to wait for a real order. Winkelstraat.nl offers REST **webhook-trigger endpoints** that re-send (replay) a webhook to your endpoint on demand, so you can verify your endpoint receives and processes each webhook correctly. Every webhook has a matching trigger endpoint, for example: - `POST /V2/winkelstraat/push_api/webhook-trigger/shipment` - `POST /V2/winkelstraat/push_api/webhook-trigger/track` - `POST /V2/winkelstraat/push_api/webhook-trigger/rma` - `POST /V2/winkelstraat/push_api/webhook-trigger/rma-item` - `POST /V2/winkelstraat/push_api/webhook-trigger/creditmemo-item` (V1 equivalents exist under `/V1/...` but are deprecated.) Call the trigger endpoint for the entity you want to test, and Winkelstraat.nl delivers the corresponding webhook to your configured URL. ## Authentication Winkelstraat sends two HTTP headers with every webhook: - **`x-version`** _(required)_ — the webhook version, `V1` or `V2`. - **`x-api-key`** _(optional)_ — a **shared secret** used to authenticate the incoming request. ### About the `x-api-key` The `x-api-key` is **not** a Magento integration token or an OAuth token. It is a free-text shared secret that you agree on together with Winkelstraat. The flow is: 1. You choose a secret value and e-mail it to Winkelstraat together with your endpoint URLs (see *Activation*). It can be any string. 2. A Winkelstraat administrator stores it on your merchant account (admin: *Merchant → General → “Push API key”*). 3. From then on, Winkelstraat includes that value as the `x-api-key` header on **every** webhook it sends to your endpoint. 4. Your endpoint compares the received `x-api-key` against the agreed secret and rejects the request (e.g. with a non-2xx status) when it does not match. Because it is a shared secret, the key travels **from Winkelstraat to you** — you never send it back to us. When no key is configured for your merchant account, the header is simply omitted. When replaying an event through a webhook-trigger endpoint (see *How to test*), you may pass the key explicitly; otherwise the key configured on your merchant account is used. ## Activation To activate the Winkelstraat.nl Sales Webhooks, e-mail the following to ; a Winkelstraat administrator then configures them on your merchant account: - the URL(s) of the endpoint(s) that should receive the webhooks, and - _(optional)_ the **`x-api-key`** shared secret you want Winkelstraat to send with every webhook, so your endpoint can authenticate the requests (see *Authentication*). Both the URLs and the API key are stored as fields on your merchant account (*Merchant → General*), so they are set by Winkelstraat — not by you calling an API. ## Delivery & retries Webhook events are sent in real time: as soon as Winkelstraat.nl registers a change, the matching webhook is sent immediately. If your server does not accept the message (the HTTP response is not successful, or delivery fails), the retry mechanism attempts redelivery several times over the next 24 hours. ## Response codes Your endpoint should reply with one of: - **200 OK** / **202 Accepted** — received and accepted; no retry. - **406 Not accepted** — not accepted; the message will be retried. (Full per-webhook response/error codes are documented on each webhook.) # Terminology - **Order** — a purchase request from a customer, containing one or more order items; moves through several statuses during its life cycle. - **Shipment** — a package grouping order items that are shipped together. - **Track** — tracking information used to follow a shipment's movement. - **RMA (return)** — a package grouping ordered items (RMA items) a customer returns to a merchant. - **RMA item** — a single returned item: the return reason, the customer's desired resolution, and the merchant resolution. - **Credit memo** — a correction document denoting a refunded amount. ## Servers - Live environment (production).: https://checkout.winkelstraat.nl/rest (Live environment (production).) - Test / staging environment for partner integration testing.: https://staging-magento2.winkelstraat.nl/rest (Test / staging environment for partner integration testing.) ## Topics ## Webhooks ### [Shipment](https://push-api.doc.winkelstraat.nl/group/webhook-shipment.md) - [Webhook/winkelstraat/push api/v2/shipment](https://push-api.doc.winkelstraat.nl/operation/operation-webhook-winkelstraat-push-api-v2-shipment.md) - [Webhook/winkelstraat/push api/v1/shipment](https://push-api.doc.winkelstraat.nl/operation/operation-webhook-winkelstraat-push-api-v1-shipment.md) ### [Track](https://push-api.doc.winkelstraat.nl/group/webhook-track.md) - [Webhook/winkelstraat/push api/v2/track](https://push-api.doc.winkelstraat.nl/operation/operation-webhook-winkelstraat-push-api-v2-track.md) - [Webhook/winkelstraat/push api/v1/track](https://push-api.doc.winkelstraat.nl/operation/operation-webhook-winkelstraat-push-api-v1-track.md) ### [RMA](https://push-api.doc.winkelstraat.nl/group/webhook-rma.md) - [Webhook/winkelstraat/push api/v2/rma](https://push-api.doc.winkelstraat.nl/operation/operation-webhook-winkelstraat-push-api-v2-rma.md) - [Webhook/winkelstraat/push api/v2/rma item](https://push-api.doc.winkelstraat.nl/operation/operation-webhook-winkelstraat-push-api-v2-rma-item.md) - [Webhook/winkelstraat/push api/v1/rma item](https://push-api.doc.winkelstraat.nl/operation/operation-webhook-winkelstraat-push-api-v1-rma-item.md) ### [Order Item](https://push-api.doc.winkelstraat.nl/group/webhook-order-item.md) - [Webhook/winkelstraat/push api/v2/order item](https://push-api.doc.winkelstraat.nl/operation/operation-webhook-winkelstraat-push-api-v2-order-item.md) - [Webhook/winkelstraat/push api/v1/order item](https://push-api.doc.winkelstraat.nl/operation/operation-webhook-winkelstraat-push-api-v1-order-item.md) [Powered by Bump.sh](https://bump.sh)