Skip to main content

​
Goal

Recevoir, en quasi temps réel, chaque nouvelle annonce de vente d’appartement publiée sur n’importe quel portail dans un département donné — pour vous permettre d’être le premier à contacter le vendeur.

​
Scénario

Vous êtes chasseur immobilier (ou app B2C de chasse). Vous voulez surveiller toutes les nouvelles publications d’appartements à l’achat dans le département 75 (Paris). Volume attendu : ~200-500 nouvelles annonces / jour selon la période. Vous devez aussi détecter, plus tard, les baisses de prix et les mises hors ligne sur ces mêmes annonces.
Quand utiliser ADVERTS plutôt que PROPERTIES ? Les alertes ADVERT sont nécessaires si vous voulez :
  • post-traiter les annonces / construire un pipeline de traitement interne (enrichissement, scoring, dédup custom)
  • exposer vos propres APIs à vos utilisateurs finaux
  • répliquer la BDD Fluximmo side-by-side
  • recevoir 100 % des events de dépublication (créations, mises à jour de prix, mises hors ligne)
Pour un cas d’usage purement “trouver les biens”, préférez PROPERTY (cf. property-vs-advert).

​
Étapes

1

1. Configurer un endpoint webhook qui ack en moins de 1 s

Le handler HTTP doit valider le header x-webhook-key, enqueuer le payload dans une file durable (SQS, RabbitMQ, Redis Streams), puis répondre 200. Aucun traitement métier synchrone — sinon Fluximmo timeout et retry, vous saturerez votre app.
# Pseudocode handler
on POST /webhooks/fluximmo:
    if header.x-webhook-key != EXPECTED_KEY: return 401
    enqueue(request.body)
    return 200
Smoke test depuis votre poste :
curl -i -X POST https://votre-domaine.com/webhooks/fluximmo \
  -H "Content-Type: application/json" \
  -H "x-webhook-key: $FLUXIMMO_WEBHOOK_KEY" \
  -d '{"ping": true}'
Détails — politique de retry, SLO réponse, sécurité — sur /concepts/webhooks.
2

2. Créer l'alerte ADVERT (achat appartement, dpt 75)

Filtre isOnline: true recommandé en production : vous ne recevez que des adverts actuellement publiées sur leur portail.
curl -X PUT "https://api.fluximmo.io/v2/protected/adverts/search/alerts" \
  -H "x-api-key: $FLUXIMMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_query": {
      "filterAd": {
        "location": { "department": "75" },
        "type": ["CLASS_FLAT"],
        "offer": [{ "type": "OFFER_BUY" }],
        "isOnline": true
      }
    },
    "webhook_url": "https://votre-domaine.com/webhooks/fluximmo",
    "match": ["ALERT_MATCH_CREATED"],
    "search_name": "Achat appart Paris (75)"
  }'
Conservez l’flxId retourné : c’est la clé pour modifier l’alerte plus tard (étape 4) sans perdre l’historique.
3

3. Recevoir le premier webhook (ALERT_MATCH_CREATED)

Dès qu’une nouvelle advert qualifiante est ingérée (~1 min après publication portail), Fluximmo POSTe le payload complet de l’advert sur webhook_url. Pas de refetch nécessaire, contrairement aux alertes Properties.Structure type (shape canonique — cf. exemple webhook adverts) :
{
  "data": {
    "created": [
      {
        "alert_id": "alrt_...",
        "adverts": [
          {
            "flxId": "adv_...",
            "propertyFlxId": "adv_...",
            "source": "<portail>",
            "currentPrice": { "value": 285000 },
            "habitation": { "surface": { "total": 42 }, "roomCount": 2 },
            "location": { "postalCode": "75011" },
            "isOnline": true
          }
        ]
      }
    ],
    "updated": []
  }
}
Boucle d’extraction : for entry in body.data.created: for advert in entry.adverts: .... Mappez advert.flxId sur votre BDD comme clé d’idempotence — vous recevrez parfois le même match deux fois (retry).
4

4. Étendre l'alerte aux events PRICE / REPUBLISHED / UNPUBLISHED — en PATCH

Une fois la première vague de matches digérée, étendez le tableau match avec ALERT_MATCH_ADVERT_EVENT.À faire : PATCH /v2/protected/adverts/search/alerts/{alertId} (modify in place). À NE PAS faire : DELETE puis PUT d’une nouvelle alerte — vous perdez l’historique des adverts déjà matchées, donc plus aucun event sur ces annonces.
curl -X PATCH \
  "https://api.fluximmo.io/v2/protected/adverts/search/alerts/$ALERT_FLX_ID" \
  -H "x-api-key: $FLUXIMMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match": ["ALERT_MATCH_CREATED", "ALERT_MATCH_ADVERT_EVENT"] }'
Les events arrivent désormais dans la branche data.updated[] du même webhook. Le payload updated ne porte que flxId, currentPrice, isOnline (DTO réduit) — vous dérivez côté client le type d’event en comparant avec votre état stocké : currentPrice.value change → PRICE, isOnline flip → REPUBLISHED ou UNPUBLISHED. Cf. Match types & cycle alerte.
5

5. Backfill historique : demander la réception du passé sur le webhook

Une alerte ne match que ce qui est ingéré après sa création (createdAt). Pour récupérer les annonces déjà au catalogue, écrivez à [email protected] en précisant :
  • Votre clientId
  • Le flxId de l’alerte créée à l’étape 2
  • La période de backfill souhaitée (ex. derniers 30 jours, derniers 6 mois)
  • Le volume estimé que votre webhook peut absorber
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.

​
Architecture / flow

​
Pièges fréquents

  • Traitement synchrone dans le handler → timeout, retry, cascade d’échecs sous charge. Ackez en < 1 s, traitez en worker async.
  • Idempotence oubliée : un même webhook peut être livré 2 fois (retry après timeout réseau). Dédupliquez avec une clé stable comme (advert.flxId, branch, alert_id) où branch ∈ { "created", "updated" }.
  • DELETE + recréation au lieu de PATCH → perte de l’historique des adverts matchées, donc plus aucun event sur ces annonces.
  • Pas de backfill côté serveur sans demande : l’alerte ne voit que le futur. Pour le passé, demande explicite par mail (cf. étape 5).
  • Volume sous-estimé : achat appartement dpt 75 ≈ 200-500 nouvelles annonces/jour. Provisionnez la queue et le worker en conséquence (peak intra-day en matinée).

​
Pour aller plus loin