Quickstart : Receive your first OneStock event

Who is this for?

What you will build
A live webhook endpoint using webhook.site — no server, no code, no deployment. OneStock will call it every time an order changes state. You will inspect the real payload, understand the signature header, and know exactly what your integration needs to handle.

Time to first event: ~10 minutes.

What you need before starting

• A OneStock environment (qualif or preprod) with API credentials: api_user, api_password, api_url, site_id, token

• At least one order that will change state during the test (an existing order you can manually transition in the backoffice works fine)

• A browser and any HTTP client (curl, Postman, Insomnia)

Step 1 — Get your webhook.site URL

Open https://webhook.site in your browser. A unique URL is generated immediately — copy it, you will need it in Step 3.

It looks like:

⚠️ Keep this tab open throughout the quickstart. Requests appear in the left panel in real time as OneStock calls your endpoint.

Step 2 — Configure webhook.site to return 202

OneStock requires your endpoint to return HTTP 202 Accepted within 15 seconds. If it receives anything else — or no response — it marks the delivery as failed and starts retrying.

webhook.site returns 200 by default. Change it to 202:

1. Click Edit (top right of the webhook.site interface)

2. Set Response status code to 202

3. Leave the response body empty (OneStock does not read it)

4. Click Save

Your endpoint is now ready to correctly acknowledge OneStock events.

Step 3 — Create the webhook in OneStock

Call POST /webhooks with your API credentials. Replace all placeholder values.

Field notes:

• hash_key — the secret OneStock uses to sign each request. Any string works for this quickstart. In production, generate a strong random value (e.g. openssl rand -hex 32) and store it in your secrets manager.

• topics — order_state_changed fires every time any order transitions between states. It is the most useful starting topic.

• url — paste your webhook.site URL from Step 1.

The API returns HTTP 201 with the created webhook object including its id. Save it — you will need it to clean up in Step 7.

Step 4 — Trigger an order state change

OneStock calls your endpoint automatically whenever an order transitions. The simplest trigger during a quickstart is a manual transition in the backoffice:

1. Open your OneStock backoffice

2. Go to Orders and open any order in a non-final state

3. Trigger a manual transition (available transitions depend on your workflow configuration)

Within a few seconds, a new request appears in the left panel of webhook.site.

Step 5 — Inspect the payload

Click the request in the left panel of webhook.site. You will see two important parts.

The Onestock-Signature header:

The request body — the order_state_changed payload:

This is the exact structure your production endpoint will receive. The four fields are always present:

To fetch full order details (line items, addresses, payment status, custom fields), use the order_id to call GET /orders/{order_id} from your backend.

Step 6 — Understand the signature

Every request from OneStock includes an Onestock-Signature header. Your production endpoint must verify it before processing the payload — this proves the request genuinely came from OneStock.

The signature format:

How it is computed by OneStock:

1. Concatenate: payload = "{timestamp}.{raw_request_body}"

2. Compute: HMAC-SHA256(payload, hash_key) using the hash_key you set in Step 3

3. OneStock includes up to 3 hashes (h0, h1, h2) to support key rotation without downtime

What your endpoint must do:

1. Extract the timestamp from the header

2. Reject requests where now - timestamp > 6 hours (replay attack protection)

3. Recompute HMAC-SHA256("{timestamp}.{raw_body}", your_hash_key)

4. Compare against h0, h1, h2 — accept if any matches

5. Return 202 immediately if valid; return 401 if invalid

Quick verification with the values from your webhook.site request — replace with your actual values:

Full implementation examples in Node.js, Python, PHP, and Ruby are in the Webhooks reference — Legitimacy Check section.

Step 7 — Clean up

Delete the test webhook when you are done so it does not accumulate unnecessary events. Use the id returned in Step 3:

What's next?

• Subscribe to more topics — parcel_state_changed, line_item_group_state_changed, and more are listed in the List of standard webhook topics.

• Build your real endpoint — return 202 in under 300 ms, verify the signature, process asynchronously via a queue. See the Webhooks reference for retry behaviour, idempotency requirements, and performance best practices.

• Use the order_id to call back into OneStock — after receiving an event, call PATCH /orders/{id} to enrich the order or trigger the next workflow transition. See the Workflow Extensibility — Introduction for the full webhook + PATCH API pattern with a Fraud check example.

• Monitor your production webhooks — use the backoffice webhook monitoring view to inspect delivery status, retries, and errors. See Webhook monitoring and troubleshoot.