Webhooks and API Keys in PortalX
Webhooks send real-time notifications to your own system when something happens in QrX, such as a payment or a delivery. API keys let your system create transactions through the QrX API. The API documentation is at qrx.eu/api.
API Keys
Each sales channel has its own API key: Settings > Business > Merchant Channels, open the channel, Settings tab, API Key (permission Manage Channels). The key is stored securely and shown in full only once, when you click Regenerate API Key. Copy it immediately. Regenerating stops every integration that still uses the old key.
Under the API key you find the block API access. A key starts with Full access. Switch on Restrict this key to limit the key to the parts of the API you tick, for example only reading stock. See "Restrict an API Key (API Access)".
Creating a Webhook
Go to Settings > Advanced > Webhooks.
Enter a name and your endpoint URL (https).
Choose the API version and optionally one channel (or All Channels).
Click the events you want to receive. Use Customize payload to choose the fields sent for an event.
Keep Active on. While a webhook is paused, events are skipped, not queued.
Events
Transaction: created, paid, expired, refunded, cancelled and status changed.
Shipment: created, shipped, delivered and label created.
Order: cancelled. Payment: payout processed. Delivery: confirmed.
Return events: requested, information required, approved, rejected, label issued, in transit, received, inspected, resolved, refunded, cancelled and more.
Fulfilment (QrX WMS):
picklist/created,picklist/completed,fulfilment/picked,fulfilment/packedandfulfilment/exception. See "Pack Station and Pick Lists".Stock (QrX WMS warehouse stock):
stock/adjusted(the stock of an item changed in a warehouse) andstock/low(an item dropped to its low stock alert level). They go to every active webhook that ticked them, also to a webhook for one channel. See "Stock and Warehouse Webhooks".
Security
Every delivery is signed. Verify the X-QrX-Signature header with your webhook's signing secret; X-QrX-Event and X-QrX-Delivery-Id identify the event and delivery. Use Rotate to change the secret: it applies to all following deliveries immediately, so update your endpoint first.
Failures and Testing
Failure Notifications: choose team members to email. A warning is sent after 6 hours of continuous failures, and the webhook is disabled automatically after 24 hours. Fix your endpoint and switch the webhook on again in the editor.
Send Test sends a sample event, even while the webhook is disabled.
Delivery Logs: search by transaction ID, order ID or event. Statuses: Queued, Delivering, Delivered, Retrying, Failed and Cancelled. Open a delivery to see the request and response, Redeliver it or cancel it.
The editor shows delivered and failed counts for the last 24 hours. In the danger zone you can purge the history or delete the webhook.
Connecting Apps (OAuth)
Some apps, such as the QrX Shopify app, connect through a consent screen ("Connect QrX"). You choose one channel and click Allow. The app can then create pay-at-delivery transactions and shipping labels and read payment and shipment status for that channel only. It cannot change billing, users or other channels.
When to Contact Our Support Team
Contact QrX when deliveries fail although your endpoint returns 2xx, when signatures do not verify with the current secret, or when you need an event that is not in the list. Include the webhook name and a delivery ID.