Webhook events and signature verification

Every delivery is an HTTPS POST with a JSON body and three headers:

Header	Contents
`x-orbit-webhook-signature`	`sha256=<hex>` — HMAC-SHA256 of `${timestamp}.${rawBody}` using your endpoint’s `whsec_...` secret
`x-orbit-webhook-timestamp`	Unix timestamp used in the signature
`x-orbit-webhook-event-id`	Unique delivery ID — deduplicate on this; retries reuse it

Failed deliveries are retried up to 6 times with backoff (10-second timeout per attempt). Respond with any 2xx quickly and process asynchronously. An endpoint that fails 20 consecutive deliveries is automatically disabled.

Verifying signatures

Compute the signature from the raw request body, compare in constant time, and reject deliveries with a timestamp older than five minutes. This protects you from replayed deliveries:

JavaScript

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

const TOLERANCE_SECONDS = 300;

function verifyOrbitWebhook(secret, headers, rawBody) {
  const timestamp = headers["x-orbit-webhook-timestamp"];
  const signature = headers["x-orbit-webhook-signature"];
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;
  const expected = `sha256=${createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")}`;
  const a = Buffer.from(expected);
  const b = Buffer.from(signature || "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Python

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300

def verify_orbit_webhook(secret: str, headers: dict, raw_body: bytes) -> bool:
    timestamp = headers["x-orbit-webhook-timestamp"]
    signature = headers.get("x-orbit-webhook-signature", "")
    try:
        if abs(time.time() - float(timestamp)) > TOLERANCE_SECONDS:
            return False
    except ValueError:
        return False
    expected = "sha256=" + hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

`profile.updated`

Sent when a watcher run adds new events to a profile. The delivery carries the events themselves: events holds the new timeline entries in the exact shape profile reads return in sections.eventsTimeline — title, description, date with datePrecision and dateBasis, and the sources behind the event — so your handler has everything without a follow-up read, and a later profile read returns identical objects. newEventCount is the number of new events; changes lists the source-level deltas. runsCovered names how many completed runs the delivery folds together (runId is the newest), and updatedSections lists events_timeline when the delivery carries events.

{
  "orbitId": "83f1b564-3607-4618-b8c9-a886410ceb32",
  "watcherId": "6f2f1f37-8f9f-4a51-9a2f-2f1cbb1a9d20",
  "runId": "deep-search-v3-refresh-83f1b564-...-20260716",
  "runsCovered": 1,
  "newEventCount": 1,
  "events": [
    {
      "kind": "event",
      "title": "Example announces new venture",
      "description": "Example Person announced a new venture in July 2026...",
      "date": "2026-07",
      "datePrecision": "month",
      "dateBasis": "stated",
      "eventKey": "example-announces-new-venture",
      "updateCount": 1,
      "lastUpdatedAt": "2026-07-16T21:07:46.000Z",
      "sources": [{ "link": "https://news.example.com/story", "name": "Example News" }],
      "changes": [
        {
          "sourceLink": "https://news.example.com/story",
          "sourceName": "Example News",
          "changeKind": "new_source",
          "summary": "Coverage of the announcement..."
        }
      ]
    }
  ],
  "updatedSections": ["events_timeline"],
  "changes": [
    {
      "link": "https://x.com/example",
      "platform": "twitter",
      "change_kind": "social_post",
      "new_posts": 3,
      "summary": "3 new twitter post(s)"
    },
    {
      "link": "https://news.example.com/story",
      "change_kind": "new_source",
      "title": "Example announces new venture",
      "summary": "Coverage of the announcement..."
    }
  ]
}

events carries at most 10 entries and changes at most 25; the full timeline lives on profile reads and the full change set on watcher runs.

Slack incoming-webhook URLs receive a formatted Slack message (new-event count and a short change list) instead of this JSON. Use one for a notifications channel.

Other events

company.thesis.changed, company.alert, and portfolio.changed are delivered to endpoints subscribed to them and follow the same signing scheme. Their payloads are documented with the company intelligence APIs.

Search

Enrich

Watchers

Webhooks

Keys

Webhook events and signature verification

Verifying signatures

`profile.updated`

Other events

​Verifying signatures

​profile.updated

​Other events

Verifying signatures

`profile.updated`

Other events