Events and webhooks

Gungner tells you when something changes — a company’s registered details, a person’s address, a new sanctions hit — through one event log. Poll it with a cursor, as described below. Signed webhooks (Gungner pushing each event to a URL you register, instead of you polling) are planned for a later version — see Webhooks — and will draw from the same events, so switching to them later won’t change what you’ve already built against the log itself.

Reading with a cursor

Every event has a position in your tenant’s event log. Ask for everything since a cursor, and you get back a batch of events plus a new cursor to continue from:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.gungner.ai/v1/events?cursor=$CURSOR"

Store the cursor you get back and use it on your next call. If you present a cursor that’s invalid or has expired, you’ll get a clear error back rather than a silent restart from the beginning — treat that as its own case (re-establish your position, for example from a fresh bulk export) rather than something to blindly retry.

At-least-once delivery

Both the polling API and webhooks deliver at least once, not exactly once. Under normal conditions you’ll see each event once, but you should be prepared to see the same event more than once — for example after a webhook retry — and de-duplicate using the event’s own id. Never assume an event you’ve already processed can’t arrive again.

Webhooks (planned)

Signed webhooks — Gungner pushing each event to a URL you register, instead of you polling — are planned for a later version; the event log described above is the delivery surface today. When webhooks ship, every delivery will be signed so your endpoint can verify a request actually came from Gungner and wasn’t altered in transit. Until then, poll the event log with a cursor as described above.

Idempotency

Every event carries its own id, which is what makes at-least-once delivery safe to build against: whichever way you read an event (polling today; a webhook delivery, once that ships), recognize “I’ve already processed this one” by that id and skip reprocessing rather than acting on it twice.

Schema versioning

Every event carries a schema_version field. If you encounter a version your integration doesn’t recognize yet, that’s your signal to fall back gracefully (log it, skip it, or alert) rather than assume the payload matches the shape you built against.

What kinds of events there are

Grouped by what they’re about — see the event catalogue for the full generated list with exact payload shapes:

• Company changes — registered fields changed, officers or signatories changed, beneficial owners changed, status changed (dissolved, bankrupt, and similar).
• Person changes — address, emigration, protected-identity status, or deceased (declared, not yet emitted).
• Screening — a new hit was found on a monitored subject, or a previous hit cleared.
• Operational — a scheduled refresh completed, or a monitoring subscription is expiring soon.

What triggers these events, and how monitoring decides what to watch, is covered in Monitoring subscriptions. For what a screening hit actually means, see Screening.