Webhooks

Les alertes Stream Estate peuvent livrer chaque match sur un webhook HTTP que vous hébergez. La requête est signée HMAC-SHA256, retry-able, et fournit un eventId pour l'idempotence.

Cycle de vie

1. Créez une destination — soit directement via POST /alerts avec notificationDestination: { "webhookUrl": "..." }, soit à l'avance via POST /account/event-destinations avec l'URL de votre endpoint
2. Stockez la signingKey renvoyée dans la réponse — elle n'apparaît qu'une fois, à la création de la première destination webhook du compte, et signe tous vos webhooks
3. Recevez les événements sur votre URL. À chaque alerte qui match, l'API envoie un POST JSON signé
4. Répondez 2xx sous 30 secondes — toute autre réponse déclenche jusqu'à 4 retries en backoff exponentiel
5. Renouvelez la clé si besoin depuis la console : console.stream.estate/webhooks (l'ancienne est invalidée immédiatement)

Headers de la requête

Types d'événement

Exemple de payload

{
  "eventType": "NEW_MATCH",
  "eventId": "01929ec5-3a4f-7000-bcde-f0123456789a",
  "alert": {
    "id": "01929ec5-2b3c-7000-aaaa-b00000000000",
    "name": "Appartements Paris 11e"
  },
  "listing": {
    "id": "01929ec5-1a2b-7000-cccc-d00000000000"
  },
  "data": {
    "id": "019dedb1-fdf4-714c-8392-5b9cfd63cde3",
    "property":   { "propertyType": "FLAT", "transaction": { "type": "SELL" } /* … vue canonique complète */ },
    "publishers": [ /* PublisherSection[] dédoublonnés */ ],
    "listings":   [ /* ListingSection[] */ ]
  }
}

Le payload embarque la représentation complète du bien sous data — exactement le corps renvoyé par GET /properties/{id} (id, property, publishers, listings) — pour que vous puissiez ingérer le match sans appel API supplémentaire (facturé). data reflète l'état indexé le plus frais à la livraison, pas un instantané figé de l'événement. listing.id désigne le listing (au sein de data.listings) dont la mise à jour a déclenché l'événement, et eventId est votre clé d'idempotence.

Vérification de la signature

Chaque livraison est signée avec votre signingKey en HMAC-SHA256. Ce qui est signé n'est pas le corps seul : c'est la chaîne {X-Webhook-Timestamp}.{corps_brut} — le timestamp, un point littéral, puis les octets exacts du corps de la requête.

Pour vérifier une livraison, dans n'importe quel langage :

1. Lisez X-Webhook-Timestamp et rejetez la requête si l'écart avec votre propre horloge dépasse 5 minutes — dans un sens comme dans l'autre.
2. Construisez le payload signé : le timestamp, ., puis le corps brut de la requête.
3. Calculez HMAC-SHA256(payload_signé, signingKey) et encodez-le en hexadécimal. La valeur du header est ce condensé préfixé de sha256=.
4. Comparez avec X-Webhook-Signature en temps constant — jamais avec ==, qui divulgue la signature attendue par son temps d'exécution.

Pourquoi le timestamp fait partie de la signature

Une signature seule prouve que la livraison vient bien de nous et n'a pas été altérée. Elle ne prouve pas qu'elle est récente : une requête interceptée reste valide indéfiniment et peut être rejouée à tout moment.

Le timestamp comble cette faille, mais uniquement parce que les deux moitiés sont en place. Il se trouve à l'intérieur du payload signé, donc un attaquant ne peut pas le modifier sans invalider la signature ; et votre fenêtre de ±5 minutes empêche de réutiliser un ancien timestamp valide. Sans le contrôle d'écart, le timestamp ne protège plus rien.

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300;

export function verifyStreamEstateWebhook(rawBody, headers, signingKey) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"];
  if (!timestamp || !signature) return false;

  // Replay protection
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) {
    return false;
  }

  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", signingKey)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Idempotence

Le même eventId peut arriver plusieurs fois — un retry après un timeout côté Stream Estate ne signifie pas que votre traitement précédent a échoué. Stockez les eventId déjà traités et ignorez les doublons :

La table doit avoir id en clé primaire ou en index unique — c'est cette contrainte qui rend le contrôle atomique.

async function handleWebhook(payload) {
  const { rowCount } = await db.query(
    "INSERT INTO processed_events (id) VALUES ($1) ON CONFLICT DO NOTHING",
    [payload.eventId],
  );

  if (rowCount === 0) return; // déjà traité, ack 200

  await processMatch(payload);
}

Retries et circuit breaker

Une réponse non-2xx, un timeout (> 30s), ou une erreur de connexion déclenche un retry :

Après 5 échecs consécutifs, la destination passe en SUSPENDED (circuit breaker). Elle est ensuite sondée automatiquement (toutes les 5 minutes, puis à intervalle croissant jusqu'à 6 h) et se réactive d'elle-même dès que votre endpoint répond, avec rejeu des notifications suspendues. Pour ne pas attendre la prochaine sonde, réactivez-la depuis la console : console.stream.estate/webhooks. Détails et plafond de conservation : Notifications — circuit breaker.

Renouvellement de la clé

Le renouvellement se fait depuis la console, sur console.stream.estate/webhooks. La nouvelle clé n'est affichée qu'une seule fois ; l'ancienne est invalidée immédiatement côté Stream Estate.

Résoudre un échec de signature