Skip to main content
This guide wires up the full loop: watch a profile, get notified when something new is found, and read the structured updates. You need an API key with the watchers:write and webhooks:write scopes (get one here).
1

Register a Webhook Endpoint

Register the HTTPS endpoint that should hear about updates, and store the returned secret — it appears once.
Verify the signature on every delivery — see Events & signatures.
2

Send Yourself a Test Delivery

Check your handler now rather than at the next watcher run. This posts one signed delivery to the endpoint straight away and reports what your server answered.
The delivery is signed like a live one and carries "test": true — see Send a test delivery.
3

Create the Watcher

Use the profile id from a search or profile read. Daily is a good starting cadence; the range is hourly to every 30 days.
The response includes next_run_at. Each run monitors the profile for new information and appends what it finds — see watchers.
4

Handle profile.updated

When a run finds new information, your endpoint receives a signed profile.updated delivery carrying the events themselves — each with its title, date (+ datePrecision, dateBasis), and sources — in the exact shape profile reads return in sections.eventsTimeline, plus a changes list that names every profile section the run changed and the sources behind the update.Deduplicate on x-orbit-webhook-event-id (retries reuse it), respond 2xx fast, and process asynchronously.
5

Read the Updates

The webhook already carries the new events; sections.eventsTimeline on any profile read returns the same objects, with the profile’s full history — dated events that are created or merged as new information arrives, newest first:
For per-run detail (including billing), use watcher runs.
6

Manage Watchers in the Dashboard

Dashboard → Watchers shows every watched profile with live refresh activity, and lets you pause, resume, change intervals, and delete watchers.
7

Watch a Whole Directory

To watch many people at once, open a directory and use its Watchers tab: pick people (or all of them) and a schedule, and set the directory’s default schedule and checks so new members are easy to add. The tab’s Updates feed lists every member’s dated events with their sources, and members of the directory see the same events in its Activity view.

​
Cost Control

Each completed run uses the watcher-run rate, plus the watcher-update rate when it finds something new. See API credits for current rates. To spend less, widen interval_seconds or limit phases (for example, existing_socials to watch social activity). When credits run out, watchers pause; resume them with {"enabled": true} after topping up.