Comment configurer les notifications de fin des commandes API

Quels événements considérer comme une fin de commande

Déterminez d'abord quel statut dans l'API correspond à la fin effective d'une commande. Selon les fournisseurs, il peut s'agir d'une commande exécutée, livrée, annulée, rejetée, retournée ou partiellement exécutée. Ne liez pas votre automatisation au seul mot « succès » : une commande peut passer par plusieurs états intermédiaires, puis s'arrêter à cause d'une limite, d'une vérification ou d'une annulation.

Il ne faut pas traiter uniquement le résultat positif. Si le service envoie une notification d'erreur, d'annulation, de retour ou d'exécution partielle, elle doit aussi être enregistrée dans le système interne. Sinon, dans le panneau, le CRM ou le bot, la commande restera en attente alors que la suite de l'exécution n'aura plus lieu.

Établissez une table de correspondance des statuts

Ne transmettez pas un statut API à l'interface sans le traiter. Les noms et la logique du fournisseur peuvent changer, et un même statut interne regroupe parfois plusieurs statuts externes. Conservez la valeur d'origine séparément : elle sera utile pour analyser les erreurs et la comparer à la documentation.

• pending, created, queued — commande nouvelle ou en attente de traitement.
• processing, in_progress, running — commande en cours d'exécution.
• completed, delivered, success — commande exécutée.
• partial, partially_completed — commande partiellement exécutée.
• cancelled, rejected, failed — commande annulée ou terminée en erreur.
• refunded, returned — commande nécessitant un remboursement ou une correction.
• Statut inconnu — ne modifie pas automatiquement la fiche et est transmis pour vérification.

Les noms ci-dessus sont donnés à titre d'exemple de schéma. La table définitive doit être construite à partir des statuts de l'API concernée. L'inconvénient du mapping manuel est qu'il faut le maintenir après une mise à jour de l'API : un nouveau statut peut arriver dans le gestionnaire avant qu'une règle ne soit créée pour lui.

Choisissez les webhooks, l'interrogation de l'API ou les deux schémas

Un webhook est une requête envoyée par le service vers votre URL lors d'un changement de statut de commande. L'interrogation de l'API fonctionne à l'inverse : votre système demande périodiquement les informations sur la commande. Pour les notifications de fin, les webhooks sont généralement plus pratiques, car la mise à jour arrive sans requêtes constantes vers la méthode de vérification du statut.

• Les webhooks conviennent pour une réaction rapide : mise à jour de la fiche, lancement de l'étape suivante ou envoi d'un message au responsable.
• L'interrogation convient si le fournisseur ne prend pas en charge les notifications callback ou si le serveur n'accepte pas les requêtes externes.
• Le schéma combiné utilise les webhooks comme canal principal et l'interrogation pour détecter les commandes manquées ou bloquées.

L'inconvénient de l'interrogation est le délai et la charge supplémentaire sur l'API. L'inconvénient des webhooks est qu'il faut sécuriser l'endpoint, tenir compte des doublons et ne pas se fier à l'ordre de livraison des événements.

Configurez un endpoint pour recevoir les événements

Les notifications nécessitent une adresse HTTPS publique, accessible depuis le service API. Dans les paramètres de l'intégration, on indique généralement l'URL du gestionnaire, le secret de signature et la liste des événements : changement de statut, fin, annulation, erreur ou exécution partielle.

Réservez une route distincte uniquement pour les événements API. Cela facilite la configuration de la journalisation, la restriction d'accès, la définition de limites de requêtes et évite de mélanger le trafic de service avec les formulaires du site. N'utilisez pas l'adresse de l'environnement de test pour les commandes réelles : après la mise à jour de l'environnement, le fournisseur continuera d'envoyer les événements à l'URL enregistrée.

Avant le lancement, vérifiez la méthode de requête et le format du corps dans la documentation. Le plus souvent, il s'agit d'un POST avec du JSON, mais on rencontre aussi du form-data, des paramètres de requête ou un schéma de sérialisation propre. Une erreur d'analyse doit être consignée dans le journal, sinon il sera difficile de distinguer un payload incorrect d'une défaillance de l'application.

Conservez le lien entre la commande et l'événement

Lors de la création d'une commande via l'API, conservez l'identifiant renvoyé par le fournisseur. Stockez à côté le numéro interne de la commande, le type de service, le statut d'origine, l'heure de la dernière modification et la réponse API d'origine sous une forme sécurisée. Associez le webhook entrant par l'ID du fournisseur, et non par un lien vers la chaîne, le nom du service ou le nom du client.

Si l'API permet de transmettre un identifiant externe lors de la création, ajoutez votre numéro de commande dans un champ comme external_id ou client_reference. Cela simplifie la recherche dans les logs et l'analyse des situations litigieuses. Mais ne faites pas du numéro externe la seule clé : certains fournisseurs ne le renvoient pas dans chaque notification.

Ne créez pas de nouvelle commande à partir d'un ID inconnu provenant du webhook. Un événement inconnu doit être enregistré dans le journal et vérifié séparément. La création automatique d'une entrée peut entraîner des données erronées ou le traitement d'une requête falsifiée.

Utilisez une structure de payload claire

Les noms exacts des champs dépendent de l'API. Ce qui suit n'est pas le contrat d'un service particulier, mais un exemple d'événement JSON sur lequel s'appuyer lors de la conception du gestionnaire interne. L'important est l'identifiant de l'événement, l'ID de commande chez le fournisseur, le statut, l'heure de modification et les données de diagnostic.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

N'utilisez pas la quantité d'unités exécutées comme indicateur de fin sans le statut. Une commande peut être partiellement exécutée, et le nombre dans le payload peut être arrondi, mis à jour avec du retard ou absent. L'inconvénient de stocker le corps complet de l'événement est qu'il peut contenir des données personnelles ou des champs de service ; ces enregistrements doivent donc être masqués et leur durée de conservation limitée.

Vérifiez la signature à partir du corps brut de la requête

Une URL de gestionnaire ouverte peut recevoir une requête qui ne provient pas du service API. Si le fournisseur transmet une signature, un secret ou un token, vérifiez-les avant de modifier la commande. Le schéma courant est HMAC-SHA256 : le fournisseur calcule la signature à partir des octets du corps de la requête et d'un secret partagé, puis transmet le résultat dans un en-tête HTTP.

Le principe de calcul est le suivant : on prend le corps brut de la requête, par exemple les octets JSON sans modification, et le secret de l'intégration. On calcule ensuite le HMAC-SHA256. Si le résultat en hexadécimal correspond à la valeur de l'en-tête, le corps n'a pas été modifié après la signature et la requête provient probablement d'une partie qui connaît le secret.

Exemple conditionnel : HMAC_SHA256(secret, raw_body) = signature de l'en-tête X-Signature. Le nom de l'en-tête, l'algorithme et le format du résultat doivent être repris uniquement de la documentation de l'API. Certains services ajoutent un horodatage ou un ID d'événement à la chaîne à signer. Dans ce cas, on ne peut pas vérifier uniquement le corps JSON.

Ne modifiez pas le JSON avant de vérifier la signature

La signature se vérifie sur les octets bruts de la requête, et non sur l'objet JSON que l'application a déjà analysé et reconstruit. Une nouvelle sérialisation peut modifier l'ordre des champs, les espaces, l'échappement des caractères, le saut de ligne ou l'encodage. Pour un humain, le JSON restera identique, mais l'ensemble des octets changera et le HMAC ne correspondra plus.

Pour éviter cela, récupérez d'abord le corps brut sous forme de bytes ou de buffer, conservez-le en mémoire, calculez la signature et n'analysez le JSON qu'après une vérification réussie. N'appliquez pas au corps de trim, de conversion d'encodage, de tri des clés ni de formatage. Dans le middleware du framework, vérifiez si le JSON n'est pas analysé automatiquement avant l'accès au corps d'origine.

L'inconvénient de ce schéma est que le gestionnaire devient dépendant de l'ordre des middlewares. En cas de mauvaise configuration, l'application ne verra que l'objet transformé et les notifications légitimes commenceront à être rejetées.

Exemple de gestionnaire avec vérification HMAC

Voici un exemple conditionnel en Python. Il montre l'ordre des opérations, et non une intégration prête à l'emploi : les en-têtes, l'algorithme, le format de signature et les champs du payload doivent être remplacés par les valeurs de la documentation du fournisseur.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Pour la comparaison, utilisez une fonction qui ne s'arrête pas au premier caractère différent. Cela réduit le risque de fuite d'informations sur la signature via le temps de réponse. Ne transmettez pas le secret dans le code client, ne l'ajoutez pas à l'URL et ne l'enregistrez pas intégralement dans les logs.

Rendez le traitement des événements idempotent

Le fournisseur peut livrer plusieurs fois le même événement. Les raisons sont courantes : votre serveur a mis longtemps à répondre, la connexion a été interrompue après l'enregistrement des données, l'endpoint a temporairement renvoyé une erreur ou le service a lancé une nouvelle livraison selon ses propres règles. Une répétition ne signifie pas que l'API a créé une nouvelle commande.

L'idempotence signifie qu'un même événement ne modifie le résultat qu'une seule fois. Si l'on ne tient pas compte de cette règle, un doublon renverra un message au client, créera plusieurs tâches pour le manager, accordera une compensation ou lancera une opération répétée.

Le mieux est d'utiliser l'event_id du payload. Enregistrez-le dans une table séparée ou un journal des événements traités avec une contrainte d'unicité. S'il n'y a pas d'ID distinct, formez une clé à partir de champs stables : ID de commande du fournisseur, type d'événement, statut et heure de modification. Cette variante est moins bonne : avec des horodatages imprécis, des événements différents peuvent sembler identiques.

Enregistrez l'événement et le statut dans une seule opération

La vérification « l'événement a-t-il été traité » et l'enregistrement du résultat doivent s'exécuter de manière atomique. Sinon, deux requêtes identiques arrivées simultanément verront toutes deux l'absence d'enregistrement et lanceront l'action deux fois. Une option pratique est un index unique sur event_id et une transaction de base de données.

La suite conditionnelle du gestionnaire se présente ainsi :

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

L'inconvénient d'une réponse avec un code de succès pour une commande inconnue est que le fournisseur peut ne pas répéter la livraison. Il faut donc surveiller séparément les événements inconnus et les analyser rapidement. Si la documentation de l'API recommande un autre code de réponse pour ces cas, suivez-la.

Tenez compte du désordre des événements

Les webhooks n'arrivent pas toujours strictement dans l'ordre chronologique des changements de statut. Un événement de fin peut arriver d'abord, puis une notification retardée du statut « en cours ». Si l'on se contente d'enregistrer la dernière valeur reçue, une commande exécutée redeviendra active.

Définissez les transitions autorisées. Par exemple, un statut intermédiaire ne peut pas écraser un statut final, et une commande annulée ne passe pas à exécutée sans vérification distincte. Si l'API permet de corriger un statut final, conservez la raison, la valeur d'origine et la source de la modification.

Si le payload contient l'heure de modification de la commande, comparez-la, et non l'heure de réception du webhook. Lorsque l'API ne transmet pas cet horodatage, utilisez des priorités d'états et un rapprochement via la méthode d'obtention de la commande. L'inconvénient des priorités est qu'elles ne remplacent pas la séquence réelle, surtout si le fournisseur autorise un retour depuis un statut final.

Confirmez rapidement la livraison et placez les actions en file d'attente

N'effectuez pas d'opérations longues avant de répondre au fournisseur. La vérification de la signature, la recherche de la commande, l'enregistrement de l'événement et la mise à jour du statut peuvent généralement être terminés rapidement. L'envoi d'un message, la synchronisation avec le CRM, la génération d'un rapport ou les requêtes vers des systèmes tiers ont intérêt à être confiés à une file de tâches.

L'ordre de travail est le suivant : vérifier la signature, enregistrer de manière atomique l'événement et le changement de statut, renvoyer une réponse de succès, puis exécuter les actions secondaires. Si l'on répond avant l'enregistrement, les données seront perdues en cas de défaillance. Si l'on répond après un long envoi de notification, le fournisseur peut considérer la livraison comme échouée et envoyer un doublon.

L'inconvénient de la file d'attente est l'apparition d'un composant supplémentaire à surveiller : erreurs des tâches, délais et relances. En revanche, une défaillance dans la notification au manager ne bloque pas la réception des statuts de commande.

Configurez les notifications pour l'équipe et le client

Après un changement de statut, il n'est pas nécessaire de notifier tout le monde de la même manière. Le manager est généralement intéressé par les annulations, les erreurs, l'exécution partielle et les commandes qui ne changent pas pendant longtemps. Pour le client, un résultat clair suffit souvent : commande exécutée, annulée ou nécessitant une précision.

• Commande terminée — mise à jour dans l'espace client ou bref message au client.
• Erreur d'exécution — notification au responsable avec la raison transmise par l'API.
• Exécution partielle — tâche de vérification d'une correction, d'un remboursement ou d'une action suivante.
• Statut inconnu — enregistrement dans le journal et message au spécialiste technique.
• ID de commande inconnu — vérification séparée du lien entre votre système et le fournisseur.

N'envoyez pas de message à chaque transition technique. Le fil deviendra vite bruyant et un problème important passera inaperçu. La notification interne doit contenir le numéro de commande, le service, le statut actuel, l'ID externe et un lien vers la fiche.

Tenez un journal et rapprochez les commandes non terminées

Les logs sont nécessaires pour comprendre si le service a envoyé un événement, quel corps est arrivé, pourquoi la signature n'a pas été validée et à quelle étape le traitement s'est arrêté. Enregistrez l'heure de réception, l'ID de l'événement, l'ID de commande, le type d'événement, le résultat de la vérification de signature, le statut interne et le code de réponse. Masquez les secrets, les tokens et les données personnelles.

Surveillez séparément les erreurs de livraison, les signatures invalides, les commandes inconnues, les statuts non pris en charge, les doublons et les événements qui ne peuvent pas être appliqués en raison de l'ordre des états. La croissance de ces enregistrements peut indiquer un changement de schéma de l'API, un secret expiré, une défaillance de route ou une erreur dans la logique du gestionnaire.

Rapprochez périodiquement les commandes en statut intermédiaire via la méthode d'obtention des données de l'API. Cette vérification ne remplace pas les webhooks, mais elle aide à détecter un événement manqué, une défaillance de la file d'attente ou un cas où le statut externe a changé sans notification correcte.