Express courier. Direct.
Also overnight.
x25pronto Switzerland takes goods direct to the destination. Small loads go by car. Larger loads go by van or Van XL. Direct, express and overnight trips run Monday to Sunday when a slot is free. Free times are shown in the booking calendar. This keeps the plan clear.
Webhook implementation guide for Swiss ERP connections
Step-by-step guide to connect your Swiss ERP with courier webhooks. Covers endpoint requirements, HMAC auth, payload examples, retries and logging.
Quick answer
This guide explains how to implement webhooks reliably and securely between your Swiss ERP and a courier service. It covers endpoint design, authentication (HMAC/token), payload examples, retry strategies, and monitoring.
Why use webhooks instead of polling?
Webhooks push events from the courier service to your ERP. They reduce API calls and give faster updates. For shipment status, pickup requests or delivery confirmations, webhooks are usually more efficient than polling.
Basic requirements for the endpoint
Your ERP or a middleware must expose a public HTTPS URL with a valid TLS certificate. Accept only POST requests. Set timeouts (e.g. 5–10 seconds) and limit payload size. Use JSON as the standard payload format.
Authentication and security
Use HMAC signatures (for example HMAC-SHA256) with a shared secret to guarantee integrity and authenticity. Short-lived Bearer tokens are an alternative. Verify headers like X-Signature and X-Request-Id and check timestamps to prevent replay attacks. Enforce TLS 1.2/1.3 and restrict IPs if the courier service provides stable IP ranges.
Example payloads
Standardise fields so your ERP can parse events reliably. Example shipment status event: { "event": "shipment.updated", "id": "KD-12345", "status": "delivered", "timestamp": "2024-10-02T09:30:00Z", "metadata": { "orderId": "ORD-9876", "customerRef": "CH-001" } } For pickup requests include address, time window and packing hints. Use consistent types (ISO-8601 for timestamps, strings for IDs).
Delivery and retry strategies
The sender will retry webhook deliveries. Implement idempotent processing using a unique requestId. Treat 2xx responses as successful processing. For transient errors (5xx), the sender should use exponential backoff. Maintain a dead-letter queue or retry log on your side to avoid data loss during outages.
Error handling, logging and monitoring
Log incoming requests, signature checks and processing outcomes. Build dashboards for error rates and latency. Alert on repeated failures. Provide a health endpoint so the courier service can verify your endpoint's availability.
Frequently asked questions
How do I verify an HMAC signature?
Compute HMAC-SHA256 over the raw request body with the shared secret and compare it in constant time with the X-Signature header. Also check the timestamp header to block replay attacks.
What if the same event arrives multiple times?
Process webhooks idempotently. Record requestId or eventId and skip duplicates if the ID was already processed. This prevents double bookings and inconsistent states.
Which TLS versions should I accept?
Use TLS 1.2 or 1.3. Reject older versions and weak ciphers. Rotate certificates before expiry.
How can I test the integration locally?
Use a tunnelling tool (e.g. ngrok) or a staging endpoint. Emulate signatures and various HTTP responses to test retry and error handling.