TIC
Sign in to Lens

Webhooks & notifications

Receive watchlist events by webhook, email or SMS when monitored companies, persons, addresses, properties and vehicles change.

Watchlists tell you when something changes on the companies, persons, addresses, properties and vehicles you monitor. The full watchlist API, with members, subscriptions, event types and the event list, is described in Watchlists.

Concepts

Term Meaning
Watchlist A list of entities you monitor.
Subscription An event type the watchlist tracks. Without a subscription, no events are recorded.
Event A detected change to a member, e.g. a new address or a new beneficial owner.
Notification Where events are delivered: a webhook URL, an email address or a mobile number. Every notification on the watchlist receives the events.

Only webhooks receive the event data itself. Email and SMS carry a summary for a person to read.

Creating a webhook notification

Add a notification with destinationType 0 and your HTTPS endpoint as destination:

cURLbash
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/notifications" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "https://example.com/webhook", "destinationType": 0 }'

A webhook notification is active right away. An email notification is activated when the recipient clicks the link in a confirmation email. See Notifications for listing and deleting them.

Delivery

New events are sent as a POST with a JSON array in the body, one element per event, with the user agent Ormeo Webhook Service. Any 2xx answer counts as delivered; otherwise the delivery is retried, up to three times.

Testing a webhook

Send a sample event to check that your endpoint handles the payload. It goes through the same delivery as real events, and the response shows what was sent:

cURLbash
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/notifications/{notificationGuid}/test" \
  -H "x-api-key: YOUR_API_KEY"

The sample is built from the watchlist’s first member, with an event type that fits the member, e.g. companyAddress for a company or residentMovedIn for an address. It carries "watchListMemberSubType": "test" and no teamWatchListMemberEventId, so you can tell it from a real event. See test notification.

Payload

Webhook payloadjson
[
  {
    "teamWatchListMemberEventId": 1052231,
    "teamWatchListMemberId": 9029,
    "teamWatchListId": 18,
    "externalId": "MY_REFERENCE_1",
    "companyId": 3503318,
    "watchListMemberEventType": "companyAddress",
    "eventDate": "2026-10-02T10:49:24",
    "lastUpdatedAtUtc": "2026-10-02T11:30:09"
  },
  {
    "teamWatchListMemberEventId": 1052232,
    "teamWatchListMemberId": 9031,
    "teamWatchListId": 18,
    "addressId": 2245519,
    "watchListMemberEventType": "residentMovedIn",
    "eventDate": "2026-10-03T00:00:00",
    "lastUpdatedAtUtc": "2026-10-03T06:12:40"
  }
]
Field Meaning
teamWatchListMemberEventId The event’s ID.
teamWatchListMemberId The member the event concerns.
teamWatchListId The watchlist’s numeric ID.
externalId Your own reference for the member, when you set one.
companyId, personId, addressId, propertyId, vehicleId The monitored entity. Only the one that applies to the member is present.
watchListMemberEventType What changed, in camelCase, e.g. companyAddress, vehicleOwnerChange or residentMovedIn. All types are listed under event types.
watchListMemberSubType A finer classification for some event types, when there is one.
eventDate When the change happened.
lastUpdatedAtUtc When the event was recorded or last updated.

Fields without a value are left out of the payload.