Skip to main content
Immoteur’s webhook streams classified events in real time so you can update downstream systems without polling the API. Each notification is delivered as a JSON payload via POST to the endpoint configured in your dashboard.

​
Delivery semantics

  • Notifications are sent when a classified is created or when any normalized field is updated.
  • We also send a notification when we revisit (crawl) a classified, even if nothing changed; the average revisit cadence is ~24h. You can distinguish a revisit from an update by comparing meta.lastModifiedAt (unchanged on revisit) and meta.lastSeenAt (updated on revisit).

​
Configure the endpoint

Create a webhook from the Service → Webhooks section of the Immoteur dashboard. Point it to an HTTPS endpoint that you control and confirm the secret header configuration before saving. Create webhook form

​
Filtering the stream

The events you receive depend on the filters configured on your exporter. Combine transaction, geography, and publisher filters to keep the payload focused on relevant markets.
  • Transaction type (Required)
  • Domain source
  • Property type
  • SIREN / SIRET (Required)

​
Notification types

  • Classified notification: delivers a single classified snapshot (schema components.schemas.Classified, webhook webhooks.classified-notification). Use it to track listing‑level lifecycle and price changes.
  • Property notification: delivers an aggregated property snapshot (schema components.schemas.Property, webhook webhooks.property-notification) including the current set of associated classifieds and price history.
  • Classifieds notification: delivers batched classifieds during a bulk export (schema components.schemas.ClassifiedsExport, webhook webhooks.classifieds). Each delivery includes an exportId to correlate chunks and up to 500 entries in items, making it ideal to hydrate large datasets or backfill after downtime.

​
Classifieds export delivery

The classifieds export webhook streams classifieds sequentially and waits for your HTTP response before sending the next batch. Failure responses (non-2xx or timeout) trigger up to three retries with 10-second delays. If the third attempt still fails, the export job stops and must be restarted manually from the dashboard. Active exports are automatically triggered every day at midnight, so a healthy endpoint should receive at least one classifieds export delivery per day.

​
Payload structure

The example below shows a classified notification body aligned with the OpenAPI specification. 
{
  "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" }
      ]
    }
  }
}
Trim or map fields client-side as needed; we maintain backwards compatibility by only adding new keys.
For quality, Immoteur permanently filters out classifieds missing any of the following fields:
  • location.city.inseeCode
  • location.city.name
  • location.postcode
  • location.country
  • property.type
  • transaction.price.current
  • transaction.type
  • publisher.isProfessional

​
Circuit breaker

Immoteur uses a per‑service circuit breaker to protect your servers when retries pile up.
  • Threshold: opens when 1,000 distinct webhook events are in retry for a single service.
  • Cooldown: 10 minutes. Deliveries for that service are skipped during the cooldown (no backlog).
  • Retries: up to 3 attempts with exponential backoff (30s, 60s, 120s) by default; Retry-After / RateLimit-Reset overrides the delay.
  • Max retry delay: 5 minutes, including Retry-After / RateLimit-Reset.
When the breaker opens, we send a notification email to the service owner. Fix the endpoint and return 2xx quickly; deliveries resume automatically after the cooldown. Classifieds export batches follow their own retry rules described above.

​
Delivery best practices

  1. Respond with 2xx quickly after persisting the payload; non-success responses are retried with exponential backoff.
  2. Use the id field as an idempotency key to avoid duplicates on retries.
  3. Log delivery timestamps to monitor throughput and detect stalls; contact Immoteur support if the stream stops unexpectedly.