Webhooks immobiliers : guide pratique 2026

Le principe en une phrase

Un webhook, c'est une URL HTTPS publique que vous fournissez au système source, et que celui-ci appelle en POST dès qu'un événement survient (bien créé, modifié, supprimé).

Anatomie d'un événement Ts-Immo

Payload d'un webhook property.updated

{
  "id": "evt_a1b2c3",
  "type": "property.updated",
  "created_at": "2026-05-19T08:42:11Z",
  "data": {
    "property_id": "ts-12345",
    "reference": "APT-PARIS-001",
    "changes": ["price", "photos"]
  }
}

Sécurité : la signature HMAC

Chaque webhook Ts-Immo est signé avec HMAC-SHA256 dans l'en-tête X-Ts-Immo-Signature, à l'aide d'un secret partagé. Votre endpoint doit recalculer la signature et la comparer pour authentifier la source.

Vérification d'une signature webhook en Node.js

import crypto from 'crypto'

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Les garanties de livraison

Ts-Immo garantit la livraison "at-least-once" : un événement peut être livré plusieurs fois en cas d'échec réseau. Votre endpoint doit donc être idempotent : recevoir deux fois le même événement ne doit pas dupliquer le traitement.

Idempotence

Stockez l'id de chaque événement reçu. Si vous le revoyez, ignorez-le. C'est la règle qui sauve toutes les intégrations webhook en production.

Les retries

En cas de réponse non-2xx ou de timeout (> 5 s), Ts-Immo réessaie avec un backoff exponentiel : 30 s, 2 min, 10 min, 1 h, jusqu'à 24 h. Au-delà, l'événement est marqué en échec et visible dans le dashboard pour analyse.

Bonnes pratiques d'implémentation

1Acquitter en moins de 200 ms : empilez dans une file et traitez en arrière-plan.
2Loguer chaque événement avec son id pour traçabilité.
3Vérifier la signature HMAC avant tout traitement.
4Tolérer les événements dupliqués (idempotence).
5Mettre en place un endpoint de monitoring (taux de succès, latence).

Tester un webhook en développement

Utilisez un tunnel comme ngrok ou Cloudflare Tunnel pour exposer votre localhost. Depuis app.ts-immo.org, vous pouvez renvoyer manuellement n'importe quel événement déjà reçu, ce qui facilite le débogage.

Questions fréquentes

Quels événements émet Ts-Immo ?+

Les événements principaux sont property.created, property.updated, property.deleted, media.added, media.removed, lead.received, sync.completed et sync.failed. La liste complète est dans la documentation OpenAPI sur api.ts-immo.org/docs.

Que se passe-t-il si mon endpoint est temporairement indisponible ?+

Ts-Immo retient l'événement et réessaie avec un backoff exponentiel pendant 24 heures. Au-delà, l'événement est marqué en échec, mais une réconciliation batch quotidienne rattrape le retard sur les données du bien lui-même. Aucune donnée n'est définitivement perdue.

Peut-on filtrer les événements reçus ?+

Oui, depuis le dashboard vous choisissez les types d'événements souhaités, et vous pouvez configurer des filtres avancés (ex. uniquement les biens d'une ville donnée, ou uniquement les transactions de location). Cela évite de surcharger votre endpoint avec des événements non pertinents.

Webhooks immobiliers : guide pratique