Skip to content

Event Monitoring

Event Monitoring turns your LeapFILE account's activity into a pull-based REST feed you can forward into your own SIEM or logging platform. It lives at Account Settings → Security → Events.

Reference documents (PDF)

The page below summarizes both; download the PDFs for the full detail to hand to whoever builds the integration.

What it does

Event Monitoring exposes a read-only API that streams events from your account — file transfers sent, files downloaded by recipients, and related activity. Each event is a small JSON record with an event_id, a type, a timestamp, and a type-specific data payload.

It is a documented HTTPS endpoint, not a marketplace connector and not a webhook/push integration. Your SIEM (or a small script you run) polls it on a schedule and stores its position between calls. Because it's plain REST with NDJSON responses and Bearer-token authentication, it works with essentially any platform that can call an HTTP API — including:

  • Microsoft Sentinel — via a custom REST API connector or an Azure Function
  • Splunk — via a scripted or modular input feeding the HTTP Event Collector
  • Cribl — via a REST collector
  • Any other SIEM, log shipper, or pipeline that can poll a REST endpoint on a timer

Availability

Event Monitoring is part of the Security settings. If you don't see the Events item, contact your account representative or LeapFILE support.

Enabling it and managing the API key

  1. Go to Account Settings → Security → Events.
  2. If monitoring isn't enabled yet, enable it. This generates the account's API key.
  3. The full API key is shown only once, at creation time, and is prefixed obs_ (for example, obs_Ab3fK9x2...). Copy it and store it somewhere safe (a secrets manager).
  4. Give the API key and your site's base URL to whoever is configuring the SIEM integration.

The key can't be re-displayed

LeapFILE stores only a hash of the API key, so it cannot show you the key again later. If it's lost or you need to rotate it, generate a new key — the old key is revoked immediately.

The Events page also shows a paginated usage log: each API call's timestamp, the HTTP status it returned, and how many events it delivered. Use it to confirm your integration is polling successfully.

One API key is active per account at a time. Multiple consumers can share the same key, but each must keep its own position (cursor) and they all share the account's rate limit.

How the API works

This section is for whoever builds the integration.

Endpoint: GET https://your-company.leapfile.com/v1/events

Authentication: send the API key as a bearer token:

Authorization: Bearer obs_Ab3fK9x2...

Query parameters:

Parameter Type Default Description
cursor integer 0 Return events after this position. Omit or use 0 on the first request.
limit integer 1000 Maximum events per response (1–1000).

Response (HTTP 200): the body is NDJSON — one JSON event object per line. Key response headers:

Header Description
X-Next-Cursor The cursor to send on your next request.
X-Has-More true if another page may be available, false if you're caught up.
Content-Type application/x-ndjson
Retry-After Present only on a 429 response — seconds to wait before retrying.

Errors: 400 for an invalid cursor or limit; 401 for a missing or invalid key; 429 when rate-limited.

The cursor model

The API uses cursor-based streaming rather than date-range queries. You store a single integer — the cursor — between calls. It is:

  • Monotonically increasing — each cursor is strictly greater than the last.
  • Client-owned — the server doesn't track your position; you persist the cursor.
  • Time-ordered — events come back oldest-first, so advancing the cursor is the same as advancing forward in time. There is no earliest/latest parameter; the cursor is your time filter.
  • Gap-safe and exact — every event with an ID greater than your cursor is returned, with no duplicates.

If your integration goes offline, nothing is lost — when it restarts it resumes from the last saved cursor and picks up everything that accumulated. Cursors don't expire.

Rate limit and paging

  • Rate limit: one successful request per account per 60 seconds. Exceeding it returns 429 with a Retry-After header. A polling interval of 90 seconds is recommended.
  • Paging: limit caps events per page, not in total. If a response returns a full page and X-Has-More: true, call again with X-Next-Cursor to get the next page. Repeat until X-Has-More: false. Draining a large backlog therefore takes roughly one minute per 1,000 events.

Typical polling loop

  1. Load your saved cursor (use 0 on the first run).
  2. GET /v1/events?cursor=<cursor> → process the returned events → save X-Next-Cursor.
  3. While X-Has-More is true, repeat step 2 with the new cursor.
  4. Wait ~90 seconds, then go back to step 2.

For a brand-new integration that needs historical data, start at cursor=0 and let it drain everything (it will respect the rate limit), then keep going with the same cursor at your normal polling cadence — no separate backfill logic is needed.

SIEM-specific notes

  • Use a custom REST API connector or an Azure Function.
  • Authentication: Bearer token (the obs_ key) set in the connector configuration.
  • Polling interval: at least 90 seconds.
  • State: persist X-Next-Cursor between polling cycles using the connector's checkpoint/state mechanism.
  • Parse the response as NDJSON — one complete JSON object per line.
  • Handle 429 by waiting Retry-After seconds before retrying.
  • Use a scripted or modular input that calls the endpoint.
  • Store the cursor in a Splunk checkpoint file under $SPLUNK_HOME/var/lib/splunk/modinputs/.
  • Set a sourcetype such as observation:events.
  • The cursor replaces earliest_time / latest_time — you don't need time-based filtering.
  • Use a REST collector that pages by cursor.
  • Same pattern: read X-Next-Cursor, persist it, send it on the next request; honour Retry-After on 429.

Common questions

Which SIEMs does this integrate with? Any SIEM or log platform that can poll a REST endpoint on a schedule. There's no marketplace app — the integration is the documented /v1/events endpoint plus the API key. Microsoft Sentinel, Splunk, and Cribl have setup notes above.

How do I get the API key? Account Settings → Security → Events → enable monitoring → copy the obs_ key shown once. Lost it? Generate a new one (which revokes the old one).

I'm only getting 1,000 events. That's the per-page cap, not a total. Check X-Has-More; if it's true, call again with the X-Next-Cursor value. Repeat until it's false.

I'm getting "429 Too Many Requests". You're calling more often than once per 60 seconds. Wait the number of seconds in the Retry-After header, and set your polling interval to 90 seconds or more.

Can I query a specific date range? There are no date-range parameters. For a new integration, start from cursor=0 and process forward in time order. To re-ingest, reset your stored cursor to 0 and filter by timestamp on your side.

What happens if my collector is down for a while? Nothing is lost. When it comes back, it resumes from the last saved cursor and picks up everything that accumulated.