Webhooks are a way to receive notifications from Retino about various events. Instead of periodically downloading information via API, you can create a webhook, and we will send you notifications about changes in Retino in real-time to a specified address.
You can find webhook settings in Settings > Webhooks, where you can create and monitor existing webhooks.
Creating a Webhook
Add a new URL on your server to receive webhooks, for example, your-store.com/retino-webhook. This will be the address where we will send notifications about selected events using the POST method in JSON format.
Then, go to Settings > Webhooks and click Add endpoint. Webhooks are integrated into Retino Tracking Automation, so create a new automation here, select the desired triggering event you want to be notified about, and choose Webhook as the action, entering the newly created URL from your store. Webhooks are configured at the account level and are not limited to individual users.
Once you have a new webhook created, you can try sending a test event, which can be found in the details of this newly created webhook. After sending the test event, you will see the data sent to your server, the status code of your server's response, and the data your server sent as a response. This information is very helpful in finding integration errors.
Security
All events sent by our server to your webhook URL include the X-Retino-Secret header in the following format:
X-Retino-Secret: <token>
This header is used for request authentication. You can find this header in the individual webhook settings.
Renewing the Secret Token
If you suspect your token has been compromised, you can renew it in the webhook settings.
IMPORTANT: After renewing the token, your server may not be able to receive webhooks until you deploy the new token.
Use HTTPS
We strongly recommend using the encrypted HTTPS protocol for communication. If your webhook uses HTTP, we will notify you in the webhook settings.
Event Types
A webhook can be linked to several event types simultaneously. Each event sends information about the ticket, products, shipping, and associated order.
Shipping created
Shipping status changed
Shipping status unchanged for N days
Package awaiting at branch for N days
N days remaining of package storage at branch
Data Format
The webhook sends data in JSON format. The data format is identical to the Shipping model from the Tracking API. Each event sends a complete shipping instance containing status history, exceptions, and assigned tags.
{ "carrier": "TOPTRANS", "carrier_estimated_delivery": null, "delivered_at": "2024-11-05T12:09:00+01:00", "delivery_type": "TO_ADDRESS", "destination_country": "CZ", "id": "3104447e-d019-453c-96ec-2805daf937b4", "issues": [ { "created_at": "2024-11-05T04:30:00+01:00", "is_resolved": false, "note": "", "shipping_id": "3104447e-d019-453c-96ec-2805daf937b4", "status": "EXCEPTION", "sub_status": "EXCEPTION", "type": null } ], "last_sync_at": "2024-12-18T14:30:45.300195+01:00", "order_code": "ORDER-CODE", "ordered_at": "2024-10-31T15:02:00+01:00", "original_tracking_number": "TEST-TRACKING-NUMBER", "picked_from_branch_at": null, "pickup_at": "2024-11-04T09:57:00+01:00", "source": null, "status": "DELIVERED", "stored_until": null, "sub_status": "DELIVERED", "tags": [ "049a18e5-5378-42b2-bfc0-19bcee2a02d7" ], "tracking": [ { "carrier_description": "Package delivered", "created_at": "2024-11-05T12:09:00+01:00", "location": "001 - Prague", "status": "DELIVERED", "sub_status": "DELIVERED" }, { "carrier_description": "Package out for delivery", "created_at": "2024-11-05T09:18:00+01:00", "location": "001 - Prague", "status": "OUT_FOR_DELIVERY", "sub_status": "OUT_FOR_DELIVERY" }, { "carrier_description": "Sorting error at depot", "created_at": "2024-11-05T04:30:00+01:00", "location": "001 - Prague", "status": "EXCEPTION", "sub_status": "EXCEPTION" }, { "carrier_description": "Package at delivery center", "created_at": "2024-11-05T01:40:00+01:00", "location": "001 - Prague", "status": "IN_TRANSIT", "sub_status": "IN_TRANSIT__DEPOT" }, { "carrier_description": "Package dispatched to destination center", "created_at": "2024-11-04T16:22:00+01:00", "location": "-", "status": "IN_TRANSIT", "sub_status": "IN_TRANSIT" }, { "carrier_description": "Package brought to warehouse", "created_at": "2024-11-04T09:57:00+01:00", "location": "750 - Ostrava", "status": "IN_TRANSIT", "sub_status": "IN_TRANSIT__HUB" }, { "carrier_description": "Shipping order received", "created_at": "2024-11-04T06:41:00+01:00", "location": "750 - Ostrava", "status": "INFORMATION_RECEIVED", "sub_status": "INFORMATION_RECEIVED" } ], "tracking_number": "TEST-TRACKING-NUMBER", "tracking_url": "https://apis.toptrans.cz/tracking?parcel_number=TEST-TRACKING-NUMBER" }Webhook Delivery Information
Retino sends webhooks using the POST HTTP method in JSON format. Your server must be prepared to receive and respond to this data within 10 seconds with a status code <= 2xx (200, 201, …). (Redirection status codes 3xx are not accepted, as this is a POST method).
Successful Delivery
The webhook will be successfully delivered if:
Your server responds within the 10-second time limit.
The response has a successful status code (2xx).
Delivery Retries
If your server does not respond within 10 seconds or responds with an error status code, the webhook delivery will fail. Our server will retry delivery at intervals of 72 hours with exponential backoff.
If the delivery of a single webhook fails after 72 hours from creation, we will notify you by email and provide all relevant information.
If all webhooks targeting a single endpoint fail within 72 hours, we will deactivate that endpoint and notify you by email.