A Webhook is a notification sent to a URL of your choice whenever a specific event occurs.
Webhooks are useful for integration with third-party services and other external APIs that support them.
Qapla’ has two types of webhooks:
To use the APIs, you must retrieve the Private API Keys assigned to your channel(s).
These can be found in the Control Panel under:
Settings > Channels [Channel Name] > Configure > Channel > Private API KEY
Warning: the Private API Key must be protected and kept confidential.
Shipments Webhook (shipment tracking notifications)
The Shipments Webhook allows you to receive a POST notification in JSON format for every status update the carrier communicates, for example, when a shipment moves from “out for delivery” to “delivered.”
To activate the shipment tracking webhook, go to:
Settings > Channels [Channel Name] > Configure > Updates > Webhook > Notification webhook for shipments tracking
Fill in the following fields:
- Activation: enable by checking the “Enable” box
- URL: enter the destination URL that will receive the notification
- Version: choose one of the available versions
- 1.2: classic version
- 1.3: recommended version, includes product, parcel, and recipients data
Shipments Return Webhook
For return shipments managed through the Automatic Returns service (Type 3 returns, which require purchase and activation), a POST notification in JSON format will be sent each time a customer requests a return. The notification includes all details regarding the return shipment.
Additional information
The shipment tracking notification webhook is sent when:
- It is enabled in the configuration settings.
- The shipment changes status, for example, from “out for delivery” to “delivered”.
The trigger is the status change communicated by the courier.
You can check the webhook delivery history directly in Qapla.
Go to the Tracking section, select the shipment, and click on the Webhook entry.
Test
We recommend testing your endpoint using the dedicated tool: Shipments Webhook Test
Orders Webhook (shipment generation notifications)
The Orders Webhook allows you to receive a POST notification in JSON format in case of the following events:
- On creation, when the order is generated (moving from the “Create” to “Print” stage, thus creating the shipment)
- On transmission, when the created shipments are transmitted (final “Transmit” stage — the data is sent to the carrier)
To configure the shipment generation webhook, go to:
Settings > Channels [Channel Name] > Configure > Updates > Webhook > Notification webhook for shipments generation
Set the following:
- Activation: enable by checking the “Enable” box
- URL: enter the destination URL that will receive the notification
- Event: choose the desired trigger
- On creation
- On transmission
Additional Information
The shipment generation webhook is not applicable for users generating shipments via API (createLabel and confirmLabel); it is only for those generating shipments via the Qapla’ Control Panel (Create, Print, and Transmit phases).
The shipment generation webhook is sent when:
- It is enabled in the configuration settings.
- The event selected during configuration occurs.
The trigger is the event selected in the settings: either shipment creation or shipment transmission.
Test
We recommend testing your endpoint using the dedicated tool: Orders Webhook Test