How it works
Versioning
What v1 in the path and api_version in each event mean, and the current state of the contract.
The API has two version marks, and each says something different.
v1 in the path
All paths are under /v1. It is the major version of the contract: the paths, the objects and what they mean.
api_version in each event
Each event carries api_version: "2026-09-24", and the webhooks’ User-Agent repeats it (SafeOnuba-Webhooks/2026-09-24). It is the date of the version of the format that event was generated with.
Store it alongside each event you receive. If formats ever coexist, it is what will tell you which one each was written with.
Current state: preview
While the preview lasts:
- Generate your client, if you do, from the contract (OpenAPI 3.1) and regenerate it when it changes.
- Ignore fields you don’t recognise instead of failing. It is the simplest way to stop a new field breaking your integration.
- Program against the
codeof errors and against enum values, not against texts.
The contract
The OpenAPI 3.1 contract is the source of truth: the reference in this documentation is generated from it on every deployment. You can download it at /en/developers/openapi.json, and the API serves it at GET /v1/openapi.json, without a token.