Les webhooks pour les débutants : comment l’API LotShow vous prévient qu’une photo est prête

Une photo studio demande un peu de temps. Votre système pourrait demander à LotShow toutes les quelques secondes si elle est prête, ou LotShow peut prévenir votre système dès qu’elle l’est. Cette seconde méthode s’appelle un webhook, et c’est ainsi que l’API LotShow livre ses résultats.

Polling ou webhooks

Avec le polling, votre code appelle GET /v1/jobs/{id} à intervalles réguliers jusqu’à ce que le statut change. Ça fonctionne, mais la plupart de ces appels ne renvoient rien de nouveau, et plus vous traitez de voitures, plus vous en faites.

Un webhook inverse la logique. Quand vous créez un job, vous donnez une URL à LotShow. Quand le job se termine, LotShow envoie un POST HTTPS à cette URL avec le résultat. Votre système ne fait rien tant qu’il n’y a rien à faire.

Les événements

• job.completed : une photo studio est prête, avec l’URL de l’image finalisée.
• job.failed : une photo n’a pas pu être finalisée, et son crédit a été remboursé.
• credits.low : votre solde partagé est passé sous les 20 crédits.

Vous choisissez les événements que reçoit chaque endpoint : un système de stock peut écouter les photos finalisées pendant qu’un outil de facturation n’est averti que des soldes bas.

À quoi ressemble une livraison

Un job terminé arrive sous forme d’un petit corps JSON :

{
  "event": "job.completed",
  "created_at": "2026-10-14T09:41:40.000Z",
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "backdrop": "white-hall",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
  "seconds": 62,
  "credits_left": 319
}

L’id est l’id de job que vous avez reçu en créant le job. C’est pourquoi il est utile de stocker l’id de job à côté du numéro de stock dans votre propre système : le webhook vous dit quel job est terminé, et vos données vous disent à quelle voiture il correspond.

Créer un bon endpoint

1. Répondez vite. Renvoyez un statut 2xx dès que l’événement est arrivé, puis faites le vrai travail, comme télécharger l’image, en arrière-plan.
2. Attendez-vous aux doublons. Une livraison peut arriver plus d’une fois, par exemple après un délai d’expiration, car LotShow réessaie jusqu’à ce que votre endpoint réponde. Vérifiez si vous avez déjà traité un événement avant d’agir à nouveau.
3. Ne présumez pas de l’ordre. Deux jobs envoyés à une seconde d’intervalle peuvent se terminer dans n’importe quel ordre. Associez les résultats par id de job, pas par heure d’arrivée.
4. Vérifiez la signature. Chaque livraison est signée avec le secret de signature de votre compte, disponible dans les Paramètres, dans les en-têtes webhook-id, webhook-timestamp et webhook-signature (le schéma Standard Webhooks). Rejetez tout ce qui ne passe pas la vérification.
5. Journalisez tout. Conservez le corps brut et l’heure de chaque livraison. Quand quelque chose semble anormal, le journal est le premier endroit où vous regarderez.

Tester avant la mise en production

Dans les Paramètres, chaque endpoint a un bouton « Envoyer un test », et l’API propose POST /v1/webhooks/{id}/test. Tous deux envoient un événement de test à votre endpoint, pour vérifier votre handler sans dépenser de crédits. Un inspecteur de requêtes ou un tunnel local est un bon moyen de voir exactement ce que reçoit votre endpoint.

Prêt à vous lancer ? Les clés API sont incluses dans Pro et Elite : créez-en une dans les Paramètres, sous Clés API.