Webhook shipping.ordered allows integrating your shipping system with Retino. This webhook is triggered whenever shipping is successfully ordered in the Retino system and provides you with complete information about the ordered shipping.

Note: Webhooks are a premium feature included in the "API & Webhooks" extension. If you have this extension active, you can find webhook settings in Settings > Webhooks.

Activating Webhook Event

Prepare a URL endpoint on your server to receive webhooks (e.g. your-eshop.com/webhook-retino-shipping)
Go to Settings > Webhooks in Retino
Click "Create webhook"
Enter the URL of your endpoint
Select the shipping.ordered event
Save the settings

Security

Each webhook includes an authentication token in the request header to verify that the request originates from Retino:

X-Retino-Secret: <token>

You can find this token in the individual webhook settings. When receiving webhooks, you should always verify that the header contains the correct token matching your webhook.

Sample Data

Webhook shipping.ordered sends data in JSON format with the following information:

{
  "event_type": "shipping.ordered",
  "created_at": "2023-01-23T10:28:10.010Z",
  "shipping": {
    "id": "2b20e85f-2201-494a-b3f9-85d89721174e",
    "client_reference": "20210001",
    "option_name": "Zásilkovna - Na výdejní místo",
    "tracking_number": "Z3824826667",
    "tracking_url": "https://www.zasilkovna.cz/vyhledavani?number=Z3824826667",
    "customer_payment_details": [
      {
        "amount": "99.00",
        "currency": "CZK",
        "invoice_url": "https://example.com/invoice/123456.pdf"
      }
    ]
  }
}

Data Structure Description

Field	Description	Type
`event_type`	Webhook event type	String
`created_at`	Event creation timestamp	ISO 8601 DateTime
`shipping.id`	Unique shipping identifier in the Retino system	UUID
`shipping.client_reference`	Ticket code the shipping relates to	String
`shipping.option_name`	Shipping service name	String
`shipping.tracking_number`	Shipment tracking number	String
`shipping.tracking_url`	URL for tracking the shipment	URL
`shipping.customer_payment_details`	Customer payment details for shipping	Array
`shipping.customer_payment_details[].amount`	Amount customer paid for shipping	Decimal
`shipping.customer_payment_details[].currency`	Payment currency	String (ISO 4217)
`shipping.customer_payment_details[].invoice_url`	Invoice URL for shipping	URL

Using Webhook Data

Data from the shipping.ordered webhook event can be used for example to:

Update shipment information in your system
Automatically send an email to the customer with tracking information
Record shipping costs for accounting and analytical purposes
Synchronize order status between Retino and your e-shop

Receiver-Side Implementation

For proper webhook reception and processing, we recommend:

Implementing X-Retino-Secret header verification for security
Ensuring your server responds within 10 seconds (even if data processing is asynchronous)
Implementing idempotent webhook processing (same webhook might be delivered multiple times)

PHP Implementation Example

// Get data from webhook
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);
$secretToken = $_SERVER['HTTP_X_RETINO_SECRET'] ?? null;// Verify secret token
$expectedToken = 'your_secret_token'; // Obtained from Retino webhook settings
if ($secretToken !== $expectedToken) {
    http_response_code(401);
    exit('Unauthorized');
}// Quick response and asynchronous processing
http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['status' => 'accepted']);// Release connection for background processing
if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}// Process shipping data
if ($data['event_type'] === 'shipping.ordered') {
    $shipping = $data['shipping'];
    
    // Save shipment data to your database
    saveShippingData(
        $shipping['id'],
        $shipping['client_reference'],
        $shipping['tracking_number'],
        $shipping['tracking_url']
    );
    
    // Send tracking email to customer
    if (!empty($shipping['tracking_url']) && !empty($shipping['tracking_number'])) {
        sendTrackingEmail(
            $shipping['client_reference'],
            $shipping['tracking_number'],
            $shipping['tracking_url']
        );
    }
}

Monitoring and Troubleshooting

All sent webhooks and responses are available in Retino in the specific webhook detail in Webhook settings. Here you can:

See the history of sent webhooks
View request details including payload
View your server's responses
Send a test event to verify functionality

Warning: If your server doesn't respond within 10 seconds or responds with an error status code, the webhook delivery will fail. Retino will retry delivering such a webhook for 72 hours with exponential backoff between attempts (2 min, 4 min, 8 min, 16 min...) up to a maximum interval of 1 hour.

If delivery fails for 72 hours, the endpoint will be automatically deactivated and the account administrators will be notified by email.

Credit Note Webhooks

Webhooks

Shipping Order Webhook