Webhooks

Stream Estate alerts can deliver each match to an HTTP endpoint you host. The request is HMAC-SHA256 signed, retry-aware, and ships an eventId you can use as an idempotency key.

Lifecycle

1. Create a destination — either straight from POST /alerts with notificationDestination: { "webhookUrl": "..." }, or up front via POST /account/event-destinations with your endpoint URL
2. Save the signingKey returned in the response — it's shown once only, when the first webhook destination of your account is created, and it signs all your webhooks
3. Receive events at your URL. Every time an alert matches, the API posts signed JSON
4. Reply 2xx within 30 seconds — any other response triggers up to 4 retries with exponential back-off
5. Rotate the key when needed from the console: console.stream.estate/webhooks (the previous key is invalidated immediately)

Request headers

Event types

Sample payload

{
  "eventType": "NEW_MATCH",
  "eventId": "01929ec5-3a4f-7000-bcde-f0123456789a",
  "alert": {
    "id": "01929ec5-2b3c-7000-aaaa-b00000000000",
    "name": "Paris 11e flats"
  },
  "listing": {
    "id": "01929ec5-1a2b-7000-cccc-d00000000000"
  },
  "data": {
    "id": "019dedb1-fdf4-714c-8392-5b9cfd63cde3",
    "property":   { "propertyType": "FLAT", "transaction": { "type": "SELL" } /* … full canonical view */ },
    "publishers": [ /* deduplicated PublisherSection[] */ ],
    "listings":   [ /* ListingSection[] */ ]
  }
}

The payload embeds the full property representation under data — the exact body returned by GET /properties/{id} (id, property, publishers, listings) — so you can ingest the match without an extra (billed) API call. data reflects the freshest indexed state at delivery time, not a point-in-time snapshot of the event. listing.id identifies the listing (within data.listings) whose update triggered the event, and eventId is your idempotency key.

Verifying the signature

Every delivery is signed with your signingKey using HMAC-SHA256. What is signed is not the body alone: it is the string {X-Webhook-Timestamp}.{raw_body} — the timestamp, a literal dot, then the exact bytes of the request body.

To verify a delivery, in any language:

1. Read X-Webhook-Timestamp and reject the request if it drifts more than 5 minutes from your own clock — in either direction.
2. Build the signed payload: the timestamp, ., then the raw request body.
3. Compute HMAC-SHA256(signed_payload, signingKey) and hex-encode it. The header value is that digest prefixed with sha256=.
4. Compare with X-Webhook-Signature using a constant-time comparison — never ==, which leaks the expected signature through its timing.

Why the timestamp is part of the signature

A signature alone proves the delivery came from us and was not altered. It does not prove it is recent: an intercepted request stays valid forever, and can be replayed at any time.

The timestamp closes that hole, but only because both halves are in place. It sits inside the signed payload, so an attacker cannot change it without invalidating the signature; and your ±5 minute window means an old timestamp cannot be reused. Skip the drift check and the timestamp stops protecting anything.

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),
  );
}

Idempotency

The same eventId may arrive more than once — a retry after a Stream Estate-side timeout does not mean your previous handler failed. Store processed eventIds and skip duplicates:

The table needs id as a primary key or unique index — that constraint is what makes the check atomic.

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; // already handled, ack 200

  await processMatch(payload);
}

Retries and circuit breaker

A non-2xx response, a timeout (> 30s), or a connection error triggers a retry:

After 5 consecutive failures, the destination flips to SUSPENDED (circuit breaker). It is then probed automatically (every 5 minutes, then at a growing interval up to 6 h) and reactivates on its own as soon as your endpoint answers, replaying the suspended notifications. To skip the wait for the next probe, reactivate it from the console: console.stream.estate/webhooks. Details and retention cap: Notifications — circuit breaker.

Rotating the signing key

Rotation is done from the console, at console.stream.estate/webhooks. The new key is shown once only; the old one is invalidated immediately on Stream Estate's side.

Troubleshooting signature failures