Webhooks

Les webhooks vous notifient en temps réel de chaque changement sur vos missions : création, attribution d’un convoyeur, enlèvement, documents, refacturation, annulation… Plutôt que d’interroger l’API en boucle, vous recevez un POST HTTPS signé dès qu’un événement se produit. Cette page liste tous les types d’événements émis par l’API, leur déclencheur et un exemple complet de payload. Pour configurer un endpoint et valider l’authenticité d’une livraison, voir la page Vérification de signature.

Tous les événements partagent la même enveloppe JSON : { id, type, created_at, data }. Seul le contenu de data change selon le type. Branchez votre routage sur le champ type (ou l’en-tête X-MED-Event-Type), jamais sur la structure de data.

L’enveloppe d’événement

Chaque livraison transporte une enveloppe identique. C’est le contrat stable sur lequel construire votre traitement.

string

Identifiant unique de l’événement (UUID). Stable, mais pas une clé d’idempotence de livraison — pour la déduplication, utilisez l’en-tête X-MED-Delivery-Id.

string

Type d’événement (ex. transport.created). Voir le catalogue ci-dessous.

string

Horodatage de création de l’événement, au format ISO 8601 (date-time).

object

Charge utile publique propre au type d’événement. Ne contient jamais de secret ni de champ interne (rémunération convoyeur, pénalités convoyeur, etc.).

Enveloppe (exemple transport.created)

{
  "id": "8f2c1a9e-0b6d-4f2a-9c1e-2a3b4c5d6e7f",
  "type": "transport.created",
  "created_at": "2026-06-16T10:32:00Z",
  "data": {
    "id": "-O9xAbCdEf",
    "transport_id": null,
    "price": "407.44"
  }
}

En-têtes de livraison

Chaque POST sortant vers votre endpoint porte quatre en-têtes X-MED-*.

string

Type de l’événement transporté (ex. transport.created). Pratique pour router sans désérialiser le corps.

string

Identifiant stable de la livraison, conservé entre les tentatives de réessai. C’est votre clé d’idempotence côté consommateur : dédupliquez dessus.

string

Epoch en secondes au moment de l’envoi. Sert à l’anti-rejeu : rejetez une livraison dont l’horodatage s’écarte de plus de 5 minutes de l’heure courante.

string

Signature HMAC-SHA256 au format sha256=<hex>, calculée sur "{X-MED-Timestamp}.{rawBody}" avec votre signing secret. Voir Vérification de signature.

La livraison est at-least-once : un même événement peut arriver plusieurs fois. Dédupliquez systématiquement sur X-MED-Delivery-Id et répondez 2xx rapidement pour acquitter.

Vue d’ensemble du catalogue

Cycle de vie de la mission

transport.created, transport.status_changed, transport.assigned, transport.collected, transport.completed, transport.cancelled, transport.incident, transport.duplicated

Modifications

transport.dates_updated, transport.price_adjusted

Documents / PV

document.added, document.accepted, document.rejected

Diagnostic

webhook.test

Un endpoint peut s’abonner à tous les événements (*) ou à une liste explicite de types. Le tableau ci-dessous résume chaque type ; les sections suivantes détaillent le payload.

Événement	Déclencheur	`data` (résumé)
`transport.created`	Création d’une mission (`POST /transports`, ou duplication : `duplicated_from` renseigné)	`{ id, transport_id, price, duplicated_from? }`
`transport.duplicated`	La mission a servi de source à une duplication (`POST /transports/{id}/duplicate`)	`{ id, duplicated_to: { id, transport_id } }`
`transport.status_changed`	Changement de statut public (dont le passage à `cancelled`)	`{ id, transport_id, from, to }`
`transport.assigned`	Convoyeur attribué	`{ id, driver }`
`transport.collected`	Véhicule enlevé (passage `in_transit`)	`{ id, collected_at }`
`transport.completed`	Mission terminée	`{ id, completed_at }`
`transport.cancelled`	Annulation, quelle qu’en soit l’origine (API, espace client, équipes MED)	`{ id, transport_id, cancelled_at }`
`transport.incident`	Anomalie signalée	`{ id }`
`transport.dates_updated`	Modification de dates	`{ id, updated_legs }`
`transport.price_adjusted`	Refacturation	`{ id, leg, old_price_ht, new_price_ht, motif }`
`transport.price_adjusted`	Ajout d’option	`{ id, option, new_price }`
`transport.driver_validation_requested`	Le convoyeur attribué doit valider une modification de dates ou de prix. S’il refuse, il est retiré de la mission, qui repart en ligne.	`{ id, type, mode }`
`transport.price_adjusted`	Retrait d’option	`{ id, removed_option, new_price }`
`document.added`	Document ajouté	`{ id, document_key, url }`
`document.accepted`	Document accepté	`{ id, document_key, status }`
`document.rejected`	Document refusé	`{ id, document_key, status }`
`webhook.test`	Test depuis l’UI « API & Intégrations »	`{ … }`

Les événements liés au PV / inspection d’une mission (inspection.report_ready, inspection.completed, phases…) sont décrits sur leur propre page : Webhooks — Inspection / PV.

Événements de cycle de vie

Ces événements suivent la progression d’une mission. La transition typique est :

scheduled → assigned → in_transit [→ in_transit_return] → awaiting_documents → under_review → completed

incident peut survenir à tout moment ; cancelled, tant que le véhicule n’est pas parti (scheduled, ou assigned une fois l’attribution du convoyeur confirmée).

transport.created — Mission créée

Émis lorsqu’une mission est créée avec succès via POST /transports. La mission est alors au statut public scheduled.

price est le prix HT de l’aller, en chaîne décimale (ex. "407.44") — convertissez-le en nombre ;
transport_id vaut null : la référence métier (M-xxxxx) est attribuée juste après la création. Lisez-la via GET /transports/{id}.

{
  "id": "8f2c1a9e-0b6d-4f2a-9c1e-2a3b4c5d6e7f",
  "type": "transport.created",
  "created_at": "2026-06-16T10:32:00Z",
  "data": {
    "id": "-O9xAbCdEf",
    "transport_id": null,
    "price": "407.44"
  }
}

Une création rejouée (même Idempotency-Key après un timeout) n’émet pas de second transport.created pour la même mission.Quand la mission est née d’une duplication, data.duplicated_from référence la source : { "id": "-O9xSourceKey", "transport_id": "M-54300" }. Dans ce cas, price est un objet { "amount_ht": 412 } (prix HT de l’aller, en nombre) et non une chaîne : testez le type de price avant de le lire.

transport.duplicated — Mission dupliquée

Émis sur la mission source lorsqu’elle sert de base à POST /transports/{id}/duplicate. Une source ne se duplique qu’une fois : cet événement n’est donc émis qu’une seule fois par mission. La mission créée émet, elle, un transport.created classique portant duplicated_from.

{
  "id": "5d0e2b1c-9a4f-4e77-b1c2-3f4a5b6c7d8e",
  "type": "transport.duplicated",
  "created_at": "2026-09-11T14:02:41Z",
  "data": {
    "id": "-O9xSourceKey",
    "duplicated_to": { "id": "-OabcDEF123", "transport_id": "M-58121" }
  }
}

transport.status_changed — Changement de statut

Émis à chaque transition de statut public. Les champs from et to utilisent le vocabulaire public stable (jamais les statuts internes).

{
  "id": "c3a7d210-4e9f-4b6a-9f1d-77e0c2b8a1f4",
  "type": "transport.status_changed",
  "created_at": "2026-06-16T11:05:12Z",
  "data": {
    "id": "-O9xAbCdEf",
    "transport_id": "M-54321",
    "from": "assigned",
    "to": "in_transit"
  }
}

Valeurs possibles : scheduled, assigned, in_transit, in_transit_return, awaiting_documents, under_review, completed, incident, cancelled.

transport.assigned — Convoyeur attribué

Émis lorsqu’un convoyeur est attribué à la mission. L’identité du convoyeur est partielle (prénom/nom, téléphone et email masqués) conformément au RGPD.

{
  "id": "1b9e44c8-2f0a-4d3e-8c6b-9a0d1e2f3a4b",
  "type": "transport.assigned",
  "created_at": "2026-06-16T11:04:00Z",
  "data": {
    "id": "-O9xAbCdEf",
    "driver": {
      "name": "Lucas D."
    }
  }
}

transport.collected — Véhicule enlevé

Émis lorsque le véhicule est enlevé (passage au statut public in_transit).

{
  "id": "5d2c8e91-7a3b-4c1d-9e0f-6b5a4c3d2e1f",
  "type": "transport.collected",
  "created_at": "2026-06-16T12:18:45Z",
  "data": {
    "id": "-O9xAbCdEf",
    "collected_at": "2026-06-16T12:18:30Z"
  }
}

transport.completed — Mission terminée

Émis lorsque la mission est terminée (statut public completed).

{
  "id": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
  "type": "transport.completed",
  "created_at": "2026-06-16T18:42:10Z",
  "data": {
    "id": "-O9xAbCdEf",
    "completed_at": "2026-06-16T18:41:55Z"
  }
}

transport.cancelled — Mission annulée

Émis une seule fois, peu après l’annulation (de façon asynchrone), quelle qu’en soit l’origine : POST /transports/{id}/cancel, votre espace client ou les équipes MED. La mission reste lisible au statut public cancelled ; un transport.status_changed vers cancelled l’accompagne, et une annulation n’émet jamais transport.completed.La charge se limite à { id, transport_id, cancelled_at }. Elle ne contient ni le motif ni les frais d’annulation. Les frais figurent dans la réponse 200 de POST /transports/{id}/cancel (penalty, return_included) — conservez-la ; l’état de la mission se lit via GET /transports/{id}. Le motif n’est renvoyé nulle part : gardez-le de votre côté.

{
  "id": "2e4f6a8c-0b1d-4e3f-8a5c-7b9d0e1f2a3c",
  "type": "transport.cancelled",
  "created_at": "2026-06-16T09:15:02Z",
  "data": {
    "id": "-O9xAbCdEf",
    "transport_id": "M-54321",
    "cancelled_at": "2026-06-16T09:15:02Z"
  }
}

transport.incident — Anomalie signalée

Émis lorsqu’une anomalie est signalée sur la mission (statut public incident).

{
  "id": "7c1d3e5f-9a2b-4c6d-8e0f-1a3b5c7d9e0f",
  "type": "transport.incident",
  "created_at": "2026-06-16T14:27:33Z",
  "data": {
    "id": "-O9xAbCdEf"
  }
}

Événements de modification

transport.dates_updated — Dates modifiées

Émis lorsqu’une ou plusieurs jambes voient leurs dates modifiées (via PATCH /transports/{id}/dates). Le champ updated_legs liste uniquement les jambes réellement modifiées.

{
  "id": "4a6c8e0f-2b1d-4e3f-9a5c-6b8d0e1f3a5c",
  "type": "transport.dates_updated",
  "created_at": "2026-06-17T08:00:00Z",
  "data": {
    "id": "-O9xAbCdEf",
    "updated_legs": ["enlevement-aller"]
  }
}

Valeurs possibles de updated_legs : enlevement-aller, livraison-aller, enlevement-retour, livraison-retour.

transport.price_adjusted — Refacturation ou option

Émis après une refacturation (POST /transports/{id}/price-adjustments) ou un ajout/retrait d’option (POST/DELETE /transports/{id}/options/...). Le contenu de data dépend de l’origine de l’ajustement — seul le prix HT facturé au client est exposé, jamais la rémunération convoyeur.Refacturation d’une jambe :

{
  "id": "6b8d0f2a-4c3e-4f5a-8b7d-9e1f3a5c7b9d",
  "type": "transport.price_adjusted",
  "created_at": "2026-06-17T09:30:12Z",
  "data": {
    "id": "-O9xAbCdEf",
    "leg": "aller",
    "old_price_ht": 180.5,
    "new_price_ht": 210.0,
    "motif": "Distance revue à la hausse"
  }
}

Ajout d’une option :

{
  "id": "7c9e1a3b-5d4f-4a6c-9c8e-0f2a4b6c8d0e",
  "type": "transport.price_adjusted",
  "created_at": "2026-06-17T09:31:00Z",
  "data": {
    "id": "-O9xAbCdEf",
    "option": "nettoyage_interieur",
    "new_price": 205.5
  }
}

Retrait d’une option :

{
  "id": "8d0f2b4c-6e5a-4b7d-8d9f-1a3b5c7d9e0f",
  "type": "transport.price_adjusted",
  "created_at": "2026-06-17T09:32:00Z",
  "data": {
    "id": "-O9xAbCdEf",
    "removed_option": "nettoyage_interieur",
    "new_price": 180.5
  }
}

Événements de documents

Ces événements suivent le cycle de vie des documents et PV de la mission. Le champ document_key identifie le document concerné.

document.added — Document ajouté

Émis lorsqu’un document est ajouté à la mission (via POST /transports/{id}/documents ou en interne).

{
  "id": "0c2e4a6c-8b0d-4e1f-9a3c-5b7d9e0f1a3c",
  "type": "document.added",
  "created_at": "2026-06-16T16:20:00Z",
  "data": {
    "id": "-O9xAbCdEf",
    "document_key": "BON_CONVOYAGE_1",
    "url": "https://files.myexpressdriver.com/docs/bon-convoyage-1.pdf"
  }
}

document.accepted — Document accepté

Émis lorsqu’un document passe au statut accepted.

{
  "id": "3d5f7a9c-1b2e-4d6f-8a0c-2b4d6e8f0a2c",
  "type": "document.accepted",
  "created_at": "2026-06-16T17:05:40Z",
  "data": {
    "id": "-O9xAbCdEf",
    "document_key": "BON_CONVOYAGE_1",
    "status": "accepted"
  }
}

document.rejected — Document refusé

Émis lorsqu’un document est refusé. Le commentaire interne de rejet n’est jamais exposé : le client voit seulement que le document est passé au statut refused.

{
  "id": "5f7a9c1e-3d4f-4a6c-8b0d-1e3f5a7c9b0d",
  "type": "document.rejected",
  "created_at": "2026-06-16T17:12:08Z",
  "data": {
    "id": "-O9xAbCdEf",
    "document_key": "BON_CONVOYAGE_1",
    "status": "refused"
  }
}

Le statut d’un document peut valoir waiting, accepted ou refused.

Événement de diagnostic

webhook.test — Test de configuration

Émis quand vous cliquez sur « Tester » dans l’onglet « API & Intégrations » de votre profil client. Utilisez-le pour valider que votre endpoint reçoit, vérifie la signature et répond 2xx correctement. Le contenu de data est libre et ne reflète aucune mission réelle.

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "type": "webhook.test",
  "created_at": "2026-06-17T10:00:00Z",
  "data": {
    "message": "Ceci est un événement de test."
  }
}

Souscription et réconciliation

Choisir les types à recevoir

À la configuration d’un endpoint, abonnez-vous à * (tous les événements) ou à une liste explicite de types (ex. transport.created, transport.completed).

Vérifier chaque livraison

Validez la signature X-MED-Signature et l’horodatage X-MED-Timestamp avant de traiter le corps. Voir Vérification de signature.

Dédupliquer et acquitter

Dédupliquez sur X-MED-Delivery-Id, puis répondez 2xx rapidement. Effectuez le traitement lourd en asynchrone.

Combler les trous

En cas d’endpoint indisponible, rejouez les événements manqués via GET /events?since=<ISO8601> et inspectez l’état des livraisons avec GET /webhooks/deliveries?status=failed.

Conservez le dernier created_at traité et appelez périodiquement GET /events?since=<dernier> pour garantir qu’aucun événement n’est perdu, même si un webhook a échoué.

Étapes suivantes

Vérification de signature

Recalculez le HMAC-SHA256, comparez à temps constant et bloquez les rejeux.

Réconciliation des événements

Rattrapez les événements manqués via le journal GET /events.

Démarrage

Concepts fondamentaux

Guides

Webhooks — Catalogue d'événements

L’enveloppe d’événement

En-têtes de livraison

Vue d’ensemble du catalogue

Cycle de vie de la mission

Modifications

Documents / PV

Diagnostic

Événements de cycle de vie

Événements de modification

Événements de documents

Événement de diagnostic

Souscription et réconciliation

Étapes suivantes

Vérification de signature

Réconciliation des événements

​L’enveloppe d’événement

​En-têtes de livraison

​Vue d’ensemble du catalogue

Cycle de vie de la mission

Modifications

Documents / PV

Diagnostic

​Événements de cycle de vie

​Événements de modification

​Événements de documents

​Événement de diagnostic

​Souscription et réconciliation

​Étapes suivantes

Vérification de signature

Réconciliation des événements

L’enveloppe d’événement

En-têtes de livraison

Vue d’ensemble du catalogue

Événements de cycle de vie

Événements de modification

Événements de documents

Événement de diagnostic

Souscription et réconciliation

Étapes suivantes