Refresh hooks

Planned, refresh webhooks are not yet available. Today, poll for changes using the methods below; subscribe to updates via the planned interface when it ships.

Datasets refresh on a published cadence (see metadata.accrualPeriodicity on Get a dataset). Refresh hooks will let Topolab notify your service the moment a dataset changes, instead of you polling for it.

Detect changes today (GA)

All three methods below are public and cost no credits. Pick one signal, store the last value you saw, and re-check on a schedule.

Watch dataRefreshedAt

Every dataset carries a dataRefreshedAt timestamp that advances each time a refresh lands. It is the most direct change signal: compare it to the value you last saw.

curl "https://api.topolab.nl/v1/dataset/transport_infrastructure_bushaltes" \
  | jq '.dataRefreshedAt'

"2026-05-01T02:14:00Z"

Watch metadata.modified and metadata.issued

metadata.modified is the date of the most recent refresh and metadata.issued is the first-published date. When modified advances past the value you last saw, the dataset has been refreshed.

curl "https://api.topolab.nl/v1/dataset/transport_infrastructure_bushaltes" \
  | jq '{ modified: .metadata.modified, issued: .metadata.issued }'

{ "modified": "2026-05-01", "issued": "2024-09-12" }

Poll no more often than the dataset's cadence, a monthly dataset only needs a daily check at most. This respects the rate limits and avoids wasted requests.

Watch the archive list

GET /v1/dataset/:table/archives/list returns the retained monthly snapshots. A new month appearing means a new refresh landed, and it gives you the two snapshots to diff.

curl "https://api.topolab.nl/v1/dataset/transport_infrastructure_bushaltes/archives/list" \
  | jq '.months[0]'

"2026-05"

To compute exactly what changed between two refreshes, download both archive months and diff them, see Download files (archive downloads require the ARCHIVED_DATA addon and cost 20 credits each).

The planned interface

When refresh hooks ship, you will register an HTTPS endpoint and Topolab will POST a change set to it on every dataset refresh. The designed payload describes which records were added, updated, and removed:

{
  "event": "dataset.refreshed",
  "table": "transport_infrastructure_bushaltes",
  "refreshedAt": "2026-06-01T02:14:00Z",
  "previousModified": "2026-05-01",
  "modified": "2026-06-01",
  "changeSet": {
    "added":   ["…", "…"],
    "updated": ["…", "…"],
    "removed": ["…"]
  }
}

The identifiers in added, updated, and removed reference the dataset's primary key. A consumer could then fetch only the changed records rather than re-downloading the full export.

This shape is the current design and may change before release. Delivery semantics, signing, and retry behaviour will follow the same conventions as other Topolab webhooks; see Webhook events for the platform-wide model.

Status

Capability	Status
Poll dataRefreshedAt	GA
Poll metadata.modified / metadata.issued	GA
Poll archives/list	GA
Outbound dataset.refreshed webhook	Planned

Want to be notified when refresh hooks ship, or have input on the design? Contact us.

Next

• Get a dataset, the dataRefreshedAt and metadata.modified fields.
• Download files, archive months for diffing.
• Webhook events, the planned webhook platform.