SafeOnuba API

The SafeOnuba API takes your plant’s alerts and evacuations to the systems your control room already uses: a SCADA, a PSIM or the intranet. It is meant so that the operator in your control room sees the same as the SafeOnuba dashboard, on their own screen, and can respond from there.

What you can do#

• Receive in real time every alert and every change to an evacuation with webhooks: a signed POST to your server for each event.
• Query alerts, evacuations and their headcount, who is missing, workers, watches, sites, zones and the positions the plant’s privacy level lets you see.
• Acknowledge and close alerts from your control room with PUT /v1/alerts/{id}. Always on behalf of an operator, who is recorded in the alert’s timeline.
• Catch up on what you missed if your receiver goes down: GET /v1/events returns the events from the last 30 days, byte for byte the same as the ones that were sent.
• Integrate without watches in the sandbox, with simulated SOS, fall, heat stress and full evacuation scenarios.

What it doesn’t do#

• In v1 it doesn’t start evacuations. The system proposes and a person decides in the SafeOnuba dashboard. Your control room receives the evacuation as soon as it starts and follows it until it ends.
• It doesn’t give vital signs, neither individual nor aggregated. A heat stress alert says what the worker has been told to do, not their heart rate.
• It sees no more than the dashboard. The API sees the same as a dashboard user with those permissions would. Privacy and security explains it.

Environments#

Both have the same paths and the same contract. The only things that change when you move to production are the address and the credentials.

Conventions#

• All paths are under /v1, and every event carries api_version: "2026-09-24". More in Versioning.
• Bodies are JSON, except the token request, which is application/x-www-form-urlencoded.
• Identifiers are UUIDs. Dates are ISO 8601 in UTC.
• Errors arrive as application/problem+json with the real HTTP status. See Errors.
• Lists are paginated with a cursor. See Pagination.
• Two paths are public and need no token: GET /v1/health and GET /v1/openapi.json, the contract.

How it fits into your control room#

The usual route has three parts:

1. A webhook receiver on your network, with a public https URL. It verifies the signature, responds 2xx straight away and puts the event on a queue.
2. Your control room system consumes that queue and draws the alert or the evacuation banner. Each alert carries panel_url, the link to its page in the SafeOnuba dashboard, in case the operator needs the detail.
3. Occasional API calls when they are needed: the list of who is missing in an evacuation, acknowledging an alert, or GET /v1/events to catch up after an outage.

From the moment an SOS goes off until it reaches your receiver, it normally takes 1 or 2 seconds. That is a typical measurement, not a service commitment.

Using this documentation with AI#

If you integrate with an AI assistant, give it the documentation in Markdown rather than the URL: it reads the whole thing, without menus or tabs, and with the links already complete.

• The Copy button, at the top right of each page, copies that page as Markdown.
• Every page has its text version by adding .md to the address: /en/developers/webhooks.md.
• /en/llms.txt is the index for tools that read it on their own, and /en/llms-full.txt is all the documentation as a single text.
• To generate typed code, the OpenAPI 3.1 contract is the source of truth.

All operations#

Next step#

Getting started: from access to your first webhook in five minutes.