Setting Up a Webhook Monitor
By Kooperativa Engineering
Most explanations of webhook-based monitoring stay at the concept level: subscribe, get notified, done. The part that actually trips people up during setup is the specific constraints on the webhook URL itself and the exact shape of the confirmation response, neither of which shows up in a diagram.
Creating the monitor
A monitor is created with a type, a subject URL, and a webhook endpoint. The webhook_url has real constraints worth knowing before the first attempt: it must be HTTPS, and it cannot point at a private or internal address, localhost and private IP ranges are explicitly rejected, since accepting them would let a monitor be pointed at infrastructure it should never be able to reach.
curl -X POST "https://kooperativa.io/api/v1/monitors" \
-H "Authorization: Bearer ik_live_..." \
-H "Content-Type: application/json" \
-d '{
"type": "person",
"subject_url": "https://www.linkedin.com/in/satyanadella",
"webhook_url": "https://your-app.com/webhooks/kooperativa",
"label": "Satya Nadella",
"events": ["person.job_changed", "person.title_changed"]
}'The detail that is easy to miss on creation
A successful creation returns HTTP 201, not 200, which matters if your client code checks for res.ok generically but logs a warning on anything other than exactly 200. The response includes the monitor's webhook_secret exactly once. It is not retrievable again afterward through any endpoint, so it needs to be saved immediately, before doing anything else with the response.
What happens after creation
Nothing fires until a real change is actually detected on the next data refresh for that subject. There is no way to force a test event, which means the honest way to verify a new monitor end to end is to point it at a profile or company you already expect to see a real change on soon, or to trigger a controlled change yourself if you are testing against your own tracked account.
Events omitted from the events array default to all events for that type, so a monitor created without specifying events will fire on every tracked change, not just the ones a given integration actually cares about. Being explicit about events from the start avoids a webhook handler having to filter out event types it never intended to receive.
Get started
Try Kooperativa
One API key. Person and company enrichment, structured search, and monitors under one flat license.