Webhooks and events

​

Endpoints

• The URL is https only, on a public host, with no user name or password. The API resolves the host at create and again before every delivery. A host that resolves to a private, loopback, link-local or metadata address answers 422 webhook_url_refused at create, and takes no delivery later. The API follows no redirect: a 3xx is a failed delivery.
• Before the endpoint is active, the API sends a challenge to the URL and expects it echoed. Until then the endpoint reads pending_verification. The other states are paused and disabled.
• The create response shows the signing secret once. It starts with whsec_. Store it. Every later read shows its last four characters only. The secret rotates through PATCH with rotate_secret: true. During a rotation a delivery carries the old and the new signature.
• The endpoint pins api_version at create. Every delivery to it renders the event at that version. A payload change ships as a new version, and you opt into it with a new endpoint.
• The endpoint records its creator and client. When the creator leaves the organization or revokes your application, the endpoint pauses. The owner of the organization then gets an email to confirm or delete it within 7 days.
• A paused endpoint names the cause in paused_reason: creator_left, consent_revoked or client_disabled. An owner or an admin starts it again with status set to active.

​

The signed delivery

import { createHmac, timingSafeEqual } from "node:crypto";

// secret: the whsec_ string from the create response. rawBody: the body bytes as a string, before any parse.
export function verifyDelivery(headers, rawBody, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const digest = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");
  const expected = Buffer.from(`v1,${digest}`);
  return headers["webhook-signature"].split(" ").some((candidate) => {
    const given = Buffer.from(candidate);
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

import base64
import hashlib
import hmac
import time


def verify_delivery(headers: dict, raw_body: bytes, secret: str) -> bool:
    event_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{event_id}.{timestamp}.".encode() + raw_body
    digest = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    expected = f"v1,{digest}"
    return any(hmac.compare_digest(candidate, expected) for candidate in headers["webhook-signature"].split(" "))

​

Delivery

​

The event shape

{
  "id": "evt_7Qk2mN9pR4sT",
  "type": "offer.created",
  "sequence": 48213,
  "occurred_at": "2026-10-02T14:03:07Z",
  "api_version": "2026-09-18",
  "data": {
    "id": "ofr_9Zx8Yw7Vu6Ts",
    "deal_id": "mdl_a1b2c3d4e5f6",
    "buyer_id": "byr_3Fg4Hj5Kl6Mn",
    "status": "new",
    "offer_amount": 231000,
    "emd_amount": 5000,
    "financing": "cash",
    "round": 1,
    "buyer": {
      "buyer_id": "byr_3Fg4Hj5Kl6Mn",
      "name": "Dana Rivera",
      "entity_name": "RIVERA CAPITAL LLC"
    }
  },
  "actor": { "kind": "person", "id": null, "client_id": null }
}

​

The catalogue

​

What an event says about a buyer

​

The events feed

• cursor=, the page.next_cursor of the page before this one
• types=, a comma list of event types
• from=, an RFC 3339 instant for a first read
• limit=, the page size, 1 to 100, 50 by default

​

Replay