Passer au contenu principal
Le webhook d’Immoteur diffuse, en temps réel, les événements relatifs aux annonces et vous permet de synchroniser vos systèmes sans interroger l’API en continu. Chaque notification est envoyée via POST avec un payload JSON vers l’URL configurée dans votre tableau de bord.

​
Sémantique d’envoi

  • Des notifications sont envoyées lors de la création d’une annonce ou lors de toute mise à jour d’un champ normalisé.
  • Nous envoyons aussi une notification lors d’une revisit (crawl) d’une annonce, même sans changement ; la cadence moyenne est d’environ 24 h. Vous pouvez distinguer une revisit d’une mise à jour en comparant meta.lastModifiedAt (inchangé lors d’une revisit) et meta.lastSeenAt (mis à jour lors d’une revisit).

​
Configurer l’endpoint

Créez un webhook depuis la section Service → Webhooks du tableau de bord Immoteur. Indiquez une URL HTTPS que vous maîtrisez et confirmez la configuration de l’en-tête secret avant d’enregistrer. Formulaire de création de webhook

​
Filtrer le flux

Les événements reçus dépendent des filtres configurés sur votre exportateur. Combinez des filtres transactionnels, géographiques et relatifs aux éditeurs pour cibler les marchés pertinents.
  • Type de transaction (Obligatoire)
  • Source (domaine)
  • Type de bien
  • SIREN / SIRET (Obligatoire)

​
Types de notifications

  • Notification d’annonce (classified) : envoie un snapshot d’annonce (schéma components.schemas.Classified, webhook webhooks.classified-notification). À utiliser pour suivre le cycle de vie et les variations de prix au niveau de l’annonce.
  • Notification de propriété : envoie un snapshot de propriété agrégée (schéma components.schemas.Property, webhook webhooks.property-notification) incluant l’ensemble courant des annonces associées et l’historique de prix.
  • Notification d’export d’annonces (classifieds) : envoie des listes d’annonces dans le cadre d’un export massif (schéma components.schemas.ClassifiedsExport, webhook webhooks.classifieds). Chaque envoi contient un exportId pour corréler les chunks et jusqu’à 500 entrées dans items, pratique pour hydrater de larges jeux de données ou rattraper un retard.

​
Envoi des exports d’annonces

Le webhook d’export d’annonces diffuse les annonces de façon séquentielle et attend votre réponse HTTP avant d’envoyer le batch suivant. Une réponse en échec (non-2xx ou timeout) déclenche jusqu’à trois retries espacés de 10 secondes. Si la troisième tentative échoue encore, le job d’export s’arrête et doit être relancé manuellement depuis le tableau de bord. Les exports actifs sont déclenchés chaque jour à minuit, ce qui garantit qu’un endpoint sain reçoit au moins un envoi d’export d’annonces par jour.

​
Structure du payload

L’exemple ci‑dessous illustre une notification d’annonce conforme à la spécification OpenAPI. 
{
  "id": "7f6e3b4d-9c22-46a0-8f20-0d1a2b3c4d5e",
  "status": {
    "current": "available"
  },
  "currency": "euro",
  "squareUnit": "squareMeter",
  "meta": {
    "firstSeenAt": "2025-09-15T08:10:00Z",
    "lastModifiedAt": "2025-09-15T09:00:00Z",
    "lastSeenAt": "2025-09-15T09:00:00Z",
    "removedAt": null
  },
  "source": {
    "domain": "seloger.com",
    "url": "https://www.seloger.com/annonces/achat/appartement/paris-1er-75/5-pieces/0.htm"
  },
  "publisher": {
    "isProfessional": true,
    "type": "agency",
    "id": "2c2a42a0-1a9b-4b18-9f1d-1f9b2a3c4d5e",
    "siren": "123456789"
  },
  "location": {
    "city": {
      "name": "Paris",
      "inseeCode": "75056"
    },
    "country": "france",
    "department": "75",
    "postcode": "75001"
  },
  "property": {
    "type": "apartment",
    "bedroomCount": 2,
    "roomCount": 3
  },
  "transaction": {
    "type": "sale",
    "price": {
      "current": 650000,
      "initial": 650000,
      "history": [
        { "value": 650000, "timestamp": "2025-09-15T09:00:00Z" }
      ]
    }
  }
}
Adaptez ou faites correspondre les champs côté client selon vos besoins ; nous garantissons la rétrocompatibilité en n’ajoutant que de nouvelles clés.
Pour garantir la qualité, Immoteur exclut définitivement les annonces dépourvues de l’un des champs suivants :
  • location.city.inseeCode
  • location.city.name
  • location.postcode
  • location.country
  • property.type
  • transaction.price.current
  • transaction.type
  • publisher.isProfessional

​
Circuit breaker

Immoteur utilise un circuit breaker par service pour protéger vos serveurs quand les retries s’accumulent.
  • Seuil : ouverture à 1 000 événements de webhook distincts en retry pour un même service.
  • Cooldown : 10 minutes. Les envois pour ce service sont ignorés pendant le cooldown (sans backlog).
  • Retries : jusqu’à 3 tentatives avec backoff exponentiel (30 s, 60 s, 120 s) par défaut ; Retry-After / RateLimit-Reset surcharge le délai.
  • Délai maximal de retry : 5 minutes, y compris via Retry-After / RateLimit-Reset.
Lorsqu’il s’ouvre, nous envoyons un email au propriétaire du service. Corrigez l’endpoint et répondez rapidement en 2xx ; l’envoi reprend automatiquement après le cooldown. Les exports d’annonces suivent leurs propres règles de retry décrites plus haut.

​
Bonnes pratiques de réception

  1. Répondez rapidement avec un 2xx après avoir persisté le payload ; en cas d’échec, des retries avec backoff exponentiel sont effectués.
  2. Utilisez le champ id comme clé d’idempotence pour éviter les doublons lors des retries.
  3. Journalisez les timestamps d’envoi pour surveiller le débit et détecter les interruptions ; contactez le support Immoteur si le flux s’interrompt de façon inattendue.