2xx accuse réception d’une livraison de webhook. Une réponse non-2xx ou une erreur de transport ne l’accuse pas, et le receiver doit accepter des doublons ainsi qu’un ordre de livraison non garanti.
Recevez un webhook de façon sûre
Gardez le handler HTTP minimal. N’exécutez pas de logique métier lente, d’enrichissement ou d’appel API en aval avant d’accuser réception.- Enregistrez la paire
X-Immoteur-Service-IdetX-Immoteur-Event-Id, puis persistez ou mettez durablement l’événement en queue avant de l’accuser réception. - Renvoyez
204 No Contentou une autre réponse2xxdès que ce travail est sûr. - Traitez l’événement dans votre propre worker ou queue après la réponse HTTP, avec des écritures idempotentes ; la queue et le worker relèvent de votre architecture d’intégration, pas d’un service Immoteur.
classified-notification-batch, accusez réception seulement après
avoir persisté le lot entier. Si une écriture du lot échoue, renvoyez une réponse
non-2xx : un réessai peut reprendre le même corps et le même
X-Immoteur-Event-Id avec un nouveau X-Immoteur-Delivery-Id.
Timeouts
Immoteur applique actuellement un timeout de connexion de 5 secondes et un timeout de requête de 5 secondes. Un receiver qui attend un travail lent peut expirer avant d’accuser réception. Persistez ou mettez en queue, puis renvoyez rapidement une réponse réussie.Lisez les en-têtes de livraison
Pour un export
classified-export, lisez le champ obligatoire exportType plutôt que de déduire le type de son contenu : full indique un Export complet et delta un Export delta. Sa valeur décrit l’export effectivement livré ; elle est présente dans chaque chunk de données et dans le message final.
Lorsqu’un Export delta demandé bascule vers un Export complet, l’export effectivement livré est un Export complet avec exportType: "full" ; les payloads envoyés au receiver n’exposent ni le mode demandé ni la raison du repli.
Ne déduisez ni un ordre de traitement, ni une garantie d’unicité pour les
exports. Pour un batch classified-notification-batch, le corps JSON et son
identifiant stable, X-Immoteur-Event-Id, restent identiques entre les réessais,
tandis que X-Immoteur-Delivery-Id change à chaque tentative HTTP.
Dédupliquez le batch avec la paire service–événement, puis appliquez un upsert
par identifiant d’annonce à chaque élément de items, en comparant par exemple
meta.lastModifiedAt avant d’écraser une donnée plus récente. Cette combinaison
absorbe les nouveaux envois du même batch et les snapshots d’une même annonce
qui arrivent dans le désordre.
Réessais et circuit breaker
Les notificationsclassified-notification-single et
classified-notification-batch utilisent le même pool HTTP, les mêmes
en-têtes, les mêmes timeouts, la même sélection de proxy, les mêmes statistiques
et le même circuit breaker. Elles suivent donc la même politique de livraison.
Une réponse non-
2xx, y compris une 4xx, n’est pas un accusé de réception
réussi. Un export peut avoir plusieurs tentatives et chunks : ne supposez ni
taille fixe ni ordre strict. Les réessais ne garantissent ni une nouvelle
livraison, ni une livraison exactement une fois, ni un ordre global.
Immoteur applique la politique de réessai adaptée après une livraison non accusée. Lorsque 1 000 événements en réessai sont en cours pour un service, son circuit s’ouvre. Le service reste actif : seules ses livraisons sont ignorées pendant le délai d’ouverture et elles ne sont pas rejouées automatiquement.
Les ouvertures effectives consécutives d’un même service utilisent successivement les délais de récupération suivants : 10, 20, 60 et 360 minutes. Après le dernier palier, les ouvertures effectives suivantes conservent ce délai maximal. À chaque passage vers l’un de ces paliers, le client reçoit un e-mail ; cet e-mail n’est pas répété lorsque le délai est déjà plafonné.
Après la fermeture du circuit, la séquence des paliers se réinitialise à l’issue d’une période de grâce de 30 minutes, si aucune nouvelle ouverture n’intervient. Aucune réponse 2xx n’est requise : l’absence de trafic compte également.
Surveillez le rétablissement de votre endpoint et reprenez la réconciliation avec un export adapté ; ne comptez pas sur un replay automatique des livraisons ignorées.
Configurez l’endpoint et les filtres dans Configurer les webhooks Immoteur. Utilisez Synchroniser les annonces pour le flux d’intégration avec export complet, notifications en direct et export delta. Utilisez Fiabilité de l’API pour les en-têtes de limite de l’API.