Skip to main content

Goal

Maintenir une copie locale (PostgreSQL/MySQL/ClickHouse) de toutes les annonces (adverts) sur un périmètre donné, synchronisée en continu sur votre webhook : alerte ADVERT pour le flux post-création + demande de backfill historique pour rattraper le passé.

Scénario

Cas d’usage typiques :
  • Notification live pour un agrégateur de recherche immobilière — pousser les nouvelles annonces vers les utilisateurs finaux dès leur ingestion ;
  • Veille temps-réel pour chasseur immobilier ou investisseur — alertes sur publications fraîches matchant un cahier des charges ;
  • Pipeline interne de traitement / réplique de DB / exposition d’API custom dérivées — enrichir les annonces avec ses propres champs (scoring, tags internes, attribution) et requêter sans appeler Fluximmo à chaque page vue ;
  • Capter 100% des événements de cycle de vie — créations, changements de prix, dépublications, republications, sur l’ensemble du périmètre.
L’objectif est d’avoir, à tout instant, la BDD locale en miroir de Fluximmo sur le périmètre choisi, avec un retard < 1 minute sur le flux courant.

Étapes

1

1. Choisir Adverts plutôt que Properties

Pour un cas réplication, adverts est toujours le bon choix :
  • Payload webhook complet : l’objet advert entier est livré dans le webhook, pas uniquement un flxId. Pas besoin de re-fetcher.
  • Suivi inter-portails : un même bien apparaissant sur deux portails distincts (par exemple un grand réseau d’agences et un mandataire indépendant) = 2 adverts liés au même propertyFlxId.
  • Events : PRICE, REPUBLISHED, UNPUBLISHED sont émis sur l’advert (pas sur la property).
  • Reconstitution Property côté DB : grouper les adverts par propertyFlxId permet de retrouver une vue dédupliquée localement.
Voir Property vs Advert pour les détails.
2

2. Préparer le schéma de table locale

L’index idx_adverts_property est ce qui permettra la reconstitution de la vue Property à l’étape 6.
3

3. Demander l'activation de l'alerte ADVERT (création par Fluximmo)

La création d’alertes ADVERT sur webhook se fait sur demande par mail. Écrivez à [email protected] en précisant :
  • Votre clientId
  • Le webhook_url cible (HTTPS public, doit ack en < 1 s)
  • Les filtres souhaités (par exemple : département 75, achat appartement, isOnline: true)
  • Les types de match désirés : ALERT_MATCH_CREATED + ALERT_MATCH_ADVERT_EVENT (créations + events PRICE/REPUBLISHED/UNPUBLISHED)
  • Le volume estimé que votre receiver peut absorber
Une fois l’alerte créée, vous recevez son flxId pour la modifier ultérieurement (en PATCH, jamais en DELETE + recréation).
4

4. Demander le backfill historique sur le même webhook

L’alerte ne fait pas de backfill automatique : elle ne match que les adverts ingérées après sa création. Pour rattraper le passé, écrivez à nouveau à [email protected] en précisant :
  • Le flxId de l’alerte créée à l’étape 3
  • La période de backfill (ex. derniers 30 jours, 6 mois, 2 ans)
  • Le volume estimé que votre receiver peut absorber pendant la rejouage
Le backfill est rejoué sur votre webhook avec le même format de payload que les matches normaux. Votre handler le traite sans changement de code, idempotence via advert.flxId.
5

5. Endpoint webhook : ACK rapide + queue

Le crawler Fluximmo attend un 200 rapide (< 1 s). Toute logique métier doit être différée dans une queue (SQS / RabbitMQ / Redis Streams).
6

6. Worker async : UPSERT + diff + reconstitution Property

Le webhook a la shape canonique { data: { created, updated } } :
  • data.created[].adverts[] = AdvertDto complet → UPSERT total côté DB
  • data.updated[].adverts[] = DTO réduit (flxId, currentPrice, isOnline uniquement) → UPDATE partiel + diff vs état stocké pour dériver les events PRICE / REPUBLISHED / UNPUBLISHED
Reconstitution de la vue Property côté DB — quand vous voulez interroger votre miroir comme si c’était /properties :
7

7. Idempotence + reconciliation

Idempotence : Fluximmo livre parfois 2 fois le même webhook (retries sur timeout). L’UPSERT par flxId rend le worker safe par construction.Reconciliation : si vous suspectez une dérive (panne queue, bug worker, perte webhook), demandez à Fluximmo un nouveau backfill ciblé sur la fenêtre concernée (par mail à [email protected], en précisant la période).
8

8. Préserver l'historique alerte

En pratique : PATCH votre alerte plutôt que DELETE + recréation, pour conserver le lien historique et continuer à recevoir des events sur les adverts déjà matchées.

Architecture / flow

Pièges fréquents

Properties au lieu de Adverts : le webhook properties ne livre que des flxId, pas le payload complet, et n’émet pas d’events PRICE/REPUBLISHED/UNPUBLISHED. Mauvais choix pour une réplication marketplace.
Pas de backfill explicite : l’alerte ne backfille pas seule. Sans étape 4 (demande par mail), vous n’aurez que les annonces créées après la création de l’alerte — trou historique permanent.
Traitement synchrone dans le webhook : un endpoint qui fait INSERT puis 200 peut dépasser 1 s sous charge → timeouts → retries → effet de bord cumulatif. Toujours ACK d’abord, traiter ensuite (étape 5).
Pas d’idempotence : sans UPSERT par flxId, les retries du crawler créent des doublons en BDD locale.
DELETE + recréer l’alerte = perte des events historiques. Toujours PATCH /alerts/{flxId} pour modifier en place.

Pour aller plus loin