Configurer les webhooks Immoteur

Configurez un service webhook lorsque votre intégration a besoin de recevoir des annonces sans polling de l’API. Immoteur envoie une requête JSON POST vers l’URL configurée dans votre dashboard.

​

Choisissez les mises à jour à recevoir

Immoteur envoie une notification d’annonce lorsqu’une annonce est créée ou lorsqu’un champ normalisé éligible change. Un revisit ne modifiant que meta.lastSeenAt est capturé pour la réconciliation par export delta et ne crée pas de notification directe. Utilisez meta.lastModifiedAt pour identifier la dernière mise à jour normalisée et meta.lastSeenAt pour identifier le dernier revisit. Il n’existe pas de webhook keep-alive périodique.

​

Configurez le service et son endpoint

Dans le dashboard Immoteur, ouvrez API → Webhooks (ou la page API → Webhooks et créez un service. Le dashboard propose les trois modes d’envoi : classified-notification-single, classified-notification-batch et classified-export. Le mode classified-notification-single est sélectionné par défaut ; utilisez un endpoint HTTPS contrôlé par votre service.

​

Filtrez le flux

Les événements reçus par un service dépendent de son filtre. Choisissez un type de filtre, puis fournissez la forme demandée par ce type. Pour une couverture globale sans filtre supplémentaire, conservez toutes les clés obligatoires, renseignez transactionType avec une valeur non nulle, puis laissez nulles les valeurs pour lesquelles le schéma l’autorise : propertyTypes, publisherType et sourceDomains.

​

Choisissez le mode d’envoi

Chaque service possède exactement un mode d’envoi. Utilisez classified-notification-single lorsque votre receiver traite un objet Classified par requête. Choisissez classified-notification-batch seulement si votre receiver sait valider, persister et accuser réception d’un lot complet. Le passage d’un mode à un autre change le corps reçu par le receiver. Vérifiez son contrat avant d’enregistrer le changement ; si un export est en cours, ce changement l’annule. Vous pouvez mettre un service en pause puis le reprendre en conservant sa configuration, mais la reprise ne garantit pas l’envoi d’un batch déjà constitué avant la pause.

​

Testez les livraisons avec le sandbox

Utilisez la route Sandbox correspondant au mode d’envoi de votre service : Pour classified-notification-batch, le sandbox accepte le même corps de batch strict. Il renvoie 200 pour un corps valide et 400 pour un corps invalide, tout en conservant les simulations de réponses existantes du sandbox.

​

Comprendre les batches de notifications d’annonce

Le corps d’un batch est strictement { "items": [...] } : il ne contient ni batchId, ni exportId, ni exportType, ni isComplete, ni type. Un batch est scellé dès qu’il contient dix identifiants d’annonce distincts. Sinon, il devient éligible lorsque son premier élément attend depuis une heure ; cette heure est un seuil d’éligibilité non glissant, pas une heure de réception garantie, car le scheduler exécuté chaque minute, la queue et la latence HTTP interviennent ensuite. Dans un batch actif, une modification ultérieure de la même annonce remplace son snapshot complet, sans augmenter le nombre d’éléments ni modifier l’ordre de sa première apparition. Le receiver reçoit donc un tableau items de un à dix objets Classified complets ; son identifiant stable de batch est X-Immoteur-Event-Id. Pour les exports classified-export, exportType est obligatoire et indique le type effectivement livré pour l’ensemble de l’export : full pour un Export complet ou delta pour un Export delta. Le champ est présent 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. Un export peut contenir plusieurs livraisons. Ne supposez ni un nombre fixe d’éléments ni un ordre de livraison. Pour associer événements live, baseline et réconciliation delta, créez des services compatibles distincts : un service classified-notification-single ou classified-notification-batch, puis un service classified-export. Ils peuvent cibler le même receiver, mais ne constituent pas le même service ; pour recevoir les mises à jour avec l’un des deux types de notification, configurez onlyNew=false. Consultez Synchroniser les annonces pour le flux complet, puis Livraison, tentatives et idempotence des webhooks avant d’implémenter votre receiver.