Webhooks: how this screen works
Webhooks send QrX events to your own system the moment they happen: a payment, a shipment, a return, a pick list and more. QrX posts a signed message to a web address (URL) you choose. This guide explains the list of webhooks and every part of the webhook editor.
What you see on this screen
Add (top right): create a new webhook.
Summary cards: Webhooks (all webhooks loaded), Active, Inactive and Needs attention (webhooks that are failing or were switched off automatically). The counts are based on the webhooks loaded in the list.
Search webhooks...: find a webhook by name or URL.
All, Active, Inactive: show only those webhooks.
Refresh (the round arrow): reloads the list.
The webhook list: loads more rows automatically as you scroll. On a small screen, scroll the table sideways to see all columns and actions.
The columns
Name: the name you gave the webhook, its URL and the API version. Click the name to open it. Click the column title to sort by name.
Channel: All Channels, or the one merchant channel this webhook is limited to.
Events: how many events the webhook listens to, with the first two names.
Status: Active, Disabled (you switched it off), Degraded (deliveries are failing right now), Auto-disabled (QrX switched it off after 24 hours of failures) or Failing (several deliveries in a row failed).
Delivered · 24h and Failed · 24h: successful and failed deliveries in the last 24 hours.
Updated: when the webhook was last changed, and the time of the last delivery. Click the column title to sort by date.
Row actions
Re-enable delivery (power icon, only on inactive webhooks): switches the webhook on again. Deliveries resume right away.
Edit (pencil): opens the webhook.
Copy: opens a new webhook with the same name (plus "copy"), events, channel, API version, payload fields and alert recipients. The URL stays empty, so you fill in the new address. Nothing is created until you save.
Delete (bin): asks you to confirm, then removes the webhook. Deliveries stop and this cannot be undone.
Create or edit a webhook
Click Add (or a webhook in the list). The left menu also shows how many events are switched on, for example 3/33. The editor has a bar at the top and a menu on the left (Endpoint, Events, Security, Alerts, Deliveries, Danger zone) to jump to each part. Security, Deliveries and Danger zone appear once the webhook is saved.
Unsaved changes or All changes saved: shows whether you still need to save.
Save: saves the webhook. You can also press Ctrl+S (Cmd+S on a Mac).
Cancel: back to the list without saving.
Send Test (saved webhooks only): sends a test event to your URL. When the webhook listens to more than one event, pick the test event in the field next to it first. The result appears under Deliveries after a few seconds. Test events are sent even when the webhook is switched off, so you can check your endpoint before you switch it back on.
Copy (saved webhooks only): starts a new webhook from this one, the same as Copy in the list.
Below the bar you see the URL (click it to copy), the status, channel, API version, number of events and the date it was created. For a saved webhook you also see the delivery health: Success rate, Median latency (how fast your endpoint answers), Deliveries · 24h and Failed · 24h (with how many are waiting for a retry).
If the webhook is failing or switched off, a coloured banner explains why. On a switched-off webhook, click Re-enable in the banner to turn deliveries back on.
Endpoint
Name (required): a name you recognise, for example "My Integration".
Endpoint URL (required): the address that receives the messages. It must start with https://. When QrX delivered to this URL successfully, you see Verified by delivery.
Channel: keep All Channels, or limit the webhook to one sales channel.
API Version: the message format your endpoint expects. The newest one is marked Latest.
Active: switch off to pause deliveries without deleting the webhook. Events that happen while it is paused are skipped, they are not sent later.
Events
Choose which events send a message. Events are grouped by subject, and the group names are shown in your language: Transaction, Shipment, Order, Payment, Delivery, Return, Fulfilment, Inbound and Stock, plus the pick list events.
Click an event to switch it on or off. Use Select all or Deselect all on a group, and the arrow to fold a group open or closed.
Filter events…: type part of an event name to find it.
The counter shows how many of the available events are switched on, for example "3 / 33 events subscribed".
Customize payload (the sliders icon next to a switched-on event): choose which fields the message contains. You see every field with its type, which fields are Required (always sent), a Sample Payload you can copy, Select all and Reset defaults. Your choice applies to every event of the same group. Click Done to close; the choice is stored when you save the webhook.
The Stock group has two events: stock/adjusted (the stock of an item changed in a warehouse) and stock/low (an item dropped to its low stock alert level or below; sent once per drop). When a fulfilment partner holds your stock, you receive these events for your own items, without locations.
Warehouse documents have their own groups: Receipts (receipt/created, receipt/line_received, receipt/completed), Purchase orders (purchase_order/created, purchase_order/sent, purchase_order/received, purchase_order/closed), Counts (count/completed, count/approved), Containers (container/created, container/moved, container/emptied), Team tasks (task/created, task/completed) and Transfers (transfer/sent, transfer/received, transfer/completed, transfer/cancelled: stock moved between your own warehouses; transfer/received is sent for every receipt and lists the received lines, and every transfer event carries the carrier and tracking). Fulfilment also has picklist/assigned, picklist/cancelled, picklist/batch_created and fulfilment/snoozed (an order was snoozed or its snooze was cleared). These events and the Inbound events belong to no sales channel: every webhook of your account that selects them receives them, also a webhook limited to one channel. Each new event has a sample payload; none of them contains prices or costs.
fulfilment/picked is sent once per order, when the pick of that order on the phone is completed.
The sample payload of the stock, pick list and fulfilment events shows a full example of the message, so you can see every field before you build your integration.
Security
Signing Secret: QrX signs every message with this secret. Use the eye icon to show or hide it and the copy icon to copy it.
Rotate…: makes a new secret. All later messages are signed with the new one right away, so update the secret in your system first.
Code examples (Node, C#, Python, PHP, cURL): show how your system checks the signature.
Signed request headers: every message carries X-QrX-Signature (the signature of the message body), X-QrX-Event (the event name) and X-QrX-Delivery-Id (a unique id of the delivery).
Alerts (Failure Notifications)
Click Add recipient and pick colleagues from your team. They get an email when this webhook keeps failing: a warning after 6 hours of failures in a row, and a message when QrX switches the webhook off after 24 hours. Click the X on a name to remove it. Save the webhook to keep the change.
Deliveries (Delivery Logs)
Every message QrX sent to this webhook, newest first. New deliveries appear by themselves while the Live badge is shown.
Search: find deliveries by transaction ID, order ID or event.
All, Delivered, Failed, Retrying: show only those deliveries.
24h, 7d, 30d: the period for the chart and the health cards at the top.
Refresh: reloads the deliveries.
The columns show the Status, Event, Transaction ID, HTTP Status your endpoint answered, Duration, Attempt number and when it was Delivered. When a message was tried more than once, click the arrow at the start of the row to see every attempt.
View delivery details (eye icon): shows the full request and response, with any error.
Redeliver: sends the same message again.
Cancel delivery (only while a delivery is queued or retrying): stops the remaining retries.
Danger zone
Purge delivery history: permanently deletes the stored requests and responses of this webhook. The webhook keeps working.
Delete Webhook: stops all deliveries and removes the webhook for good.
Both ask you to confirm first and cannot be undone.
Set up your first webhook
Click Add.
Fill in a Name and your Endpoint URL (https).
Choose a Channel if the webhook is for one channel only.
Switch on the Events you need.
Optionally add colleagues under Alerts.
Click Save. The Security section now shows your signing secret: add it to your system to check the signature.
Click Send Test and check the result under Deliveries.
Tips and common questions
"Name is required", "URL is required", "Select at least one event": fill in the missing part, then save again.
Someone else changed the webhook at the same time: QrX shows a message and lets you reload the latest version.
My webhook shows Auto-disabled: your endpoint failed for 24 hours in a row. Fix your endpoint, use Send Test to check it, then click Re-enable. Events from the time it was switched off are not sent automatically afterwards; use Redeliver on a delivery if you need it again.
How do I know a message really comes from QrX? Calculate the HMAC-SHA256 of the raw message body with your signing secret and compare it with the X-QrX-Signature header. The Security section has ready-made examples.
Need help? Click Chat at the bottom of the Help Center.