Push API Sales Webhooks

2.1.0

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 partnersupport@winkelstraat.nl; 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.

This is version 2.1.0 of this API documentation. Last update on Jul 14, 2026.