Webhooks

​

Overview

• Price events on detailed listings lag. For a listing Borough has already fetched in detail (detailScraped: true), the regular refresh does not re-read its price. A price change is detected only when Borough re-checks that listing’s detail page, which can be days to weeks later, so listing.price_decreased and listing.price_increased for those listings can arrive well after the change. See Price freshness.
• Delivery is throughput-limited. Borough publishes up to 100 detected changes every 5 minutes (about 1,200 an hour). After a refresh that detects a large batch of changes, the backlog is delivered over hours rather than minutes.

​

Event types

​

Delivery scope

• Filter in your handler. Every payload carries data.listingId (see below); ignore the ones you do not care about.
• Use a watcher. POST /v1/watchers scopes monitoring to a single listing, a single building, or one saved search, and emits changes for that target only. Watchers deliver on their own SSE stream, never to your webhook URL, and they are not a general-purpose filter: a Business customer can have at most 5 active listing watchers (polling at most hourly), and a saved-search watcher only accepts filters that match 500 or fewer active listings. For anything broader, filter webhook events in your handler.

​

Payload format

{
  "type": "listing.price_decreased",
  "data": {
    "listingId": "4961849",
    "oldValue": "5222",
    "newValue": "4900"
  },
  "timestamp": "2026-02-15 14:30:00"
}

​

Signature verification

HMAC-SHA256(key, "${webhook-id}.${webhook-timestamp}.${body}")

​

Verify with the SDK

npm install @borough/sdk standardwebhooks

import { webhookMiddleware } from '@borough/sdk/webhooks/express';

app.post('/webhooks/borough',
express.raw({ type: 'application/json' }),
webhookMiddleware(process.env.BOROUGH_WEBHOOK_SECRET, async (event) => {
console.log('Received:', event.type, event.data);
})
);

// app/api/webhooks/borough/route.ts
import { webhookHandler } from '@borough/sdk/webhooks/nextjs';

export const POST = webhookHandler(
  process.env.BOROUGH_WEBHOOK_SECRET!,
  async (event) => {
    console.log('Received:', event.type, event.data);
  }
);

​

Retry schedule

​

Delivery semantics

• Respond within 10 seconds. Each delivery attempt times out after 10 seconds, and a timeout is retried like any other failure. Return a 2xx quickly and do slow work afterwards.
• Expect duplicates. Delivery is at-least-once: after a maintenance pause or a recovery re-send, the same event can arrive more than once. Deduplicate on the webhook-id header, which stays the same for every copy of one event sent to one subscription.
• Pausing or deleting stops queued deliveries. Deliveries still in the queue for a subscription you pause or delete are cancelled rather than sent.
• Webhooks need an active Business subscription. If your subscription drops below Business, Borough deactivates your webhook subscriptions automatically.

​

Managing subscriptions