Webhooks

Recevez les changements de statut de manière fiable, vérifiable et idempotente.

Configurer un webhook

1. Ouvrez Profil → API → Webhooks.
2. Cliquez sur Ajouter un Webhook et saisissez une URL HTTPS publique.
3. Choisissez tous les événements ou uniquement les statuts utiles.
4. Enregistrez le secret affiché une seule fois, puis lancez le test.

Événements de statut

Vous pouvez écouter tous les changements ou sélectionner : DELIVERED, REFUSE, CANCELED, POSTPONED, PROGRAMMER, NOANSWER, UNREACHABLE, RETURNED, RETURNED_CLIENT, IN_PROGRESS et DISTRIBUTION.

Le payload contient notamment tracking_number, status, status_second, previous_status, previous_status_second, new_status_code et situation.

Sécuriser le récepteur

Vérifiez le HMAC-SHA256 du corps brut avec le secret. La signature arrive dans X-Webhook-Signature au format sha256=… et le type dans X-Webhook-Event. Répondez rapidement en 2xx, puis traitez le travail lourd de façon asynchrone.

{"event":"status_changed","timestamp":"2026-11-03T10:30:00+01:00","data":{"tracking_number":"PARCEL_EXEMPLE","status":"DELIVERED","previous_status":"IN_PROGRESS","new_status_code":"DELIVERED","situation":"PAID"}}

Gérer les doublons

Un événement peut être livré plusieurs fois. Stockez une empreinte ou combinez le code colis, le statut et l’horodatage.

verifyHmac(rawBody, signature, secret);
if (alreadyProcessed(event)) return 200;
queue(event);
markProcessed(event);
return 200;