Webhooks

Webhooks require a Business tier subscription.

Overview

Borough webhooks notify you when a listing changes, delivered within minutes of Borough detecting the change on its regular refresh cycle (not the instant it changes upstream). Webhooks use the Standard Webhooks specification for payload signing and verification.

Event types

Event	Description
`listing.created`	A new listing appeared in the search index
`listing.price_decreased`	Listing price dropped by more than $25
`listing.price_increased`	Listing price increased by more than $25
`listing.status_changed`	Listing status changed (e.g., ACTIVE to OFF_MARKET; off-market transitions are delivered as `listing.expired`)
`listing.expired`	Listing went off-market

Delivery scope

Subscriptions are matched on event type only. There is no per-subscription area, price, or listing filter: an active subscription receives every change of a subscribed type across the whole Borough dataset, so subscribing to listing.created means every new listing Borough indexes, citywide. Two ways to narrow that down:

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.

Payload format

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

Signature verification

Every webhook request includes three headers:

Header	Description
`webhook-id`	Unique delivery ID
`webhook-timestamp`	Unix timestamp of signing
`webhook-signature`	`v1,<base64-hmac-sha256>`

The signature is computed as:

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

Verify with the SDK

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

Failed deliveries (non-2xx responses, timeouts, and connection errors) are retried up to 7 times with exponentially increasing delays (10s, 30s, 90s, 4.5m, 13.5m, 40.5m, then 1h), so a delivery is attempted over roughly two hours before it is given up on. After all retries are exhausted, the delivery is moved to a dead letter queue. During a brief maintenance window, deliveries are parked and re-attempted rather than dropped. Parked attempts still count against the 7-retry budget, so an extended pause can send a delivery to the dead letter queue. Treat the retry budget as the ceiling in both cases.

Managing subscriptions

Use the Webhook CRUD endpoints to create, list, update, and delete subscriptions.

Getting Started

Guides

Reference

API Reference

MCP Server

SDK

Overview

Event types

Delivery scope

Payload format

Signature verification

Verify with the SDK

Retry schedule

Managing subscriptions

​Overview

​Event types

​Delivery scope

​Payload format

​Signature verification

​Verify with the SDK

​Retry schedule

​Managing subscriptions

Overview

Event types

Delivery scope

Payload format

Signature verification

Verify with the SDK

Retry schedule

Managing subscriptions