Webhook integration

How to receive file.updated notifications when hosted files change, and how to fetch the new content.

When the portal calls your URL

After an administrator replaces data.json or data.geojson, the portal sends one HTTP request per configured integration: every API key that has a non-empty webhook URL, is not disabled, and is not expired will receive a notification.

Register your endpoint

In the admin UI, open API keys and set Webhook URL on the key (create or edit).
The URL must use HTTPS and include a valid hostname.
The same API key is used later to download the file from download_url (see below).

HTTP request the portal sends

Property	Value
Method	`POST`
`Content-Type`	`application/json` (JSON body)
Body	Single JSON object (see schema below).
Timeout	About 10 seconds; respond before then.
Retries	None. A failed delivery is logged; it is not automatically retried.
Authentication	The portal does not send API keys or signatures on the outbound webhook. Use HTTPS and your own controls (e.g. secret path token, network rules) if you need to restrict who can POST to your endpoint.

JSON payload schema

Field names and types:

Field	Type	Description
`event`	string	Currently always `file.updated`.
`slot`	string	Either `json` (for `data.json`) or `geojson` (for `data.geojson`).
`filename`	string	`data.json` or `data.geojson`.
`updated_at`	string	UTC timestamp when the file was replaced, ISO-8601 with a `Z` suffix (example: `2026-04-12T15:30:00.123456Z`).
`download_url`	string	Absolute HTTPS or HTTP URL to `GET` the file. Built from the portal’s configured public base URL (currently `https://elimeter.nimling.com`).

Example payload

{
  "event": "file.updated",
  "slot": "json",
  "filename": "data.json",
  "updated_at": "2026-04-12T15:30:00.123456Z",
  "download_url": "https://elimeter.nimling.com/files/data.json"
}

Response your server must return

Return any 2xx status code if the notification was accepted. The response body is ignored. Non-2xx responses or network errors are treated as delivery failures and recorded in the portal’s activity log.

Downloading the file after a webhook

download_url points at the portal’s public file endpoint. Call it with the same API secret as the key that received the webhook:

Header X-API-Key: <your-secret>, or
Header Authorization: Bearer <your-secret>

Without a valid key, the download returns 401 Unauthorized.

Implementing the endpoint (checklist)

Expose an HTTPS URL that accepts POST with a JSON body.
Parse the JSON; handle event === "file.updated" (future event types may appear).
Use slot / filename to know which asset changed.
If you need the new bytes, GET download_url with your API key headers.
Respond with 2xx quickly (within the timeout above).
Implement idempotent handling if you might process the same logical update twice (same filename + updated_at, or your own content hash after download).

Public base URL for this deployment: https://elimeter.nimling.com (used to build download_url in each notification).