Diffuser les événements véhicule en temps réel avec les webhooks

Interroger une API à intervalle régulier est coûteux et lent : soit vous martelez l’endpoint, soit vous découvrez un changement avec des heures de retard. Les webhooks VIN Doc inversent la relation : nous appelons votre endpoint dès qu’un événement véhicule arrive. Ce guide couvre l’intégration de bout en bout, de l’abonnement à la vérification de signature jusqu’au travail ingrat mais essentiel de survivre aux relances.

S’abonner à un type d’événement

Depuis le tableau de bord, vous enregistrez une URL de rappel et sélectionnez les types d’événements qui vous intéressent : changements de titre, nouveaux enregistrements de dommage, avis de rappel ou anomalies de compteur. Chaque abonnement est cloisonné par environnement et signé avec son propre secret : un abonnement sandbox et un abonnement de production ne partagent jamais une clé.

• Abonnez-vous uniquement aux événements sur lesquels vous agirez
• Utilisez des endpoints distincts pour sandbox et production
• Versionnez votre chemin de rappel pour migrer sans risque

S’abonner à tout semble prudent mais c’est l’inverse. Chaque événement sur lequel vous n’agissez pas est du bruit dans vos logs et de la charge sur votre handler. Choisissez les événements qui changent une décision et ignorez le reste jusqu’à ce qu’ils méritent leur place.

Comprendre la charge utile de livraison

Une livraison est une petite enveloppe JSON décrivant ce qui a changé et quel véhicule est concerné, pas un rapport complet. La charge porte un identifiant d’événement, un type d’événement, le VIN concerné et un horodatage ; si vous avez besoin de l’image complète, vous récupérez le véhicule par VIN après accusé de réception.

{
  "event_id": "evt_9f3",
  "type": "title.changed",
  "vin": "1HGCM82633A004352",
  "ts": "2026-06-15T08:14:00Z"
}

Garder l’enveloppe légère permet aux livraisons de rester rapides et à votre handler de rester simple. Traitez le webhook comme une notification, pas comme la source de vérité.

Vérifier la signature

Chaque livraison inclut un en-tête de signature HMAC calculé sur le corps brut de la requête. Recalculez-le avec le secret de votre abonnement et rejetez tout ce qui ne correspond pas. C’est l’étape la plus importante : un endpoint de webhook non vérifié est une porte ouverte pour quiconque devine votre URL.

expected = hmac_sha256(secret, raw_body)
if not constant_time_equals(expected, header_signature):
    return 401

Comparez en temps constant et vérifiez contre les octets bruts, pas un objet re-sérialisé, car la re-sérialisation peut modifier subtilement le corps et casser la vérification.

Accuser réception vite, traiter ensuite

Renvoyez un 2xx en quelques secondes et faites le gros du travail de façon asynchrone. Poussez la charge utile dans une file et laissez un worker enrichir vos enregistrements. Si vous bloquez sur des appels en aval dans le handler, vous risquez des dépassements de délai et des relances inutiles qui multiplient votre charge exactement quand vous le voulez le moins.

• Répondez 2xx immédiatement, puis mettez en file
• Rendez les handlers idempotents face aux doublons
• Stockez l’identifiant d’événement pour détecter les rejeux

Gérer relances et rattrapage

Nous relançons les livraisons échouées avec un backoff exponentiel pendant 24 heures. Concevez des handlers tolérant l’arrivée d’un même événement plusieurs fois : dédupliquez sur l’identifiant d’événement pour qu’une re-livraison ne mette rien à jour qu’elle a déjà appliqué. Pour les rares trous, l’endpoint events permet de lister tout sur une plage de temps et de réconcilier : une courte panne de votre côté ne signifie jamais une perte de donnée.

Choisir la bonne granularité

Une erreur fréquente est de traiter chaque type d’événement comme aussi urgent. Un changement de titre justifie généralement une réaction immédiate ; une mise à jour d’enregistrement de routine peut très bien être groupée et traitée selon un calendrier. Mappez chaque type d’événement à la réponse qu’il mérite réellement, et acheminez-les en conséquence. Certains relèvent d’un chemin rapide qui alerte un humain, d’autres d’un récapitulatif nocturne. Mélanger les deux, c’est soit noyer vos opérateurs sous des notifications de faible valeur, soit enterrer un changement de titre critique dans le bruit. Le modèle d’abonnement vous laisse séparer cela proprement : utilisez cette souplesse plutôt que de faire passer tout par un seul handler qui doit deviner l’urgence.

Exploiter en confiance

Une intégration de webhooks saine est observable : surveillez votre latence d’accusé de réception, la profondeur de votre file et votre taux d’échec de livraison, et le tableau de bord vous montre l’historique complet de relance de chaque livraison de notre côté. Vous pouvez tout valider contre la sandbox avant la mise en production, et l’essai gratuit dure deux jours pour 3,99 € puis 49,99 €/mois, se renouvelant automatiquement et annulable à tout moment : aucune raison de tester la gestion d’événements d’abord en production. Bien fait, le webhook transforme l’historique véhicule d’une chose que vous interrogez en une chose qui vous prévient quand elle change.