# SafeOnuba API > REST API and webhooks to receive SafeOnuba alerts and evacuations in the customer’s control room (SCADA, PSIM, intranet), query them, and acknowledge or close alerts from there. v1 in preview (`api_version: "2026-09-24"`): the contract may change. Before integrating: - Sandbox: `https://sandbox.api.safeonuba.com`, with simulated watches. Production (`https://api.safeonuba.com`) is enabled when the customer is onboarded and is not yet open to the public. - OAuth2 `client_credentials` authentication at `POST /v1/oauth/token`; every other call with `Authorization: Bearer `. - The API has no CORS: call it from a server, never from the browser. - In v1 the API does not open evacuations, and it never returns vital signs. - Every webhook is signed with HMAC-SHA256 in `X-SafeOnuba-Signature`; verify it over the raw body. ## Get started - [SafeOnuba API](https://safeonuba.com/en/developers.md): Receive SafeOnuba alerts and evacuations in your control room, your SCADA, your PSIM or your intranet, and acknowledge or close alerts from there. - [Getting started](https://safeonuba.com/en/developers/getting-started.md): From access to your first webhook in five minutes: request a token, make your first call, create a destination and trigger a test alert in the sandbox. - [Authentication and scopes](https://safeonuba.com/en/developers/authentication.md): OAuth2 client_credentials: how to request a token, which scopes exist, how to rotate the client_secret without downtime and which errors the token endpoint returns. ## Concepts - [Sites and zones](https://safeonuba.com/en/developers/concepts/sites.md): A site is one of the customer’s plants. Its zones and muster points come as GeoJSON, and its privacy level decides which positions the API can see. - [Alerts](https://safeonuba.com/en/developers/concepts/alerts.md): Alert types, severity and states; the difference between the control room taking charge and the worker seeing the alert; and how to acknowledge or close it. - [Evacuations and headcount](https://safeonuba.com/en/developers/concepts/evacuations.md): Evacuation types, states and phases, the headcount by person and by muster point, ruled-out points and the list of who is missing. - [Workers and watches](https://safeonuba.com/en/developers/concepts/workers-and-watches.md): How the API identifies each person and their watch: company identifier, optional name by contract, battery, whether it’s being worn and last connection. - [Positions](https://safeonuba.com/en/developers/concepts/positions.md): When the API returns a position, what location_withheld means, how privacy zones are represented and how accurate each point is. ## Real time - [Webhooks](https://safeonuba.com/en/developers/webhooks.md): Create a destination, understand the format of each delivery, respond in time, deduplicate, filter by site or severity and send a test event. - [Verifying a webhook signature](https://safeonuba.com/en/developers/webhooks/verify-signature.md): How to check that a delivery comes from SafeOnuba: HMAC-SHA256 over the raw body, constant-time comparison, a 5-minute window and secret rotation. - [Events](https://safeonuba.com/en/developers/events.md): Event types, the common envelope and how to recover missed events with /v1/events, which returns exactly what was sent by webhook. - [Sandbox: integrating without watches](https://safeonuba.com/en/developers/sandbox.md): Run SOS, fall, heat stress or full evacuation scenarios with simulated watches and receive exactly what would arrive from a real plant. ## How it works - [Rate limits](https://safeonuba.com/en/developers/rate-limits.md): Requests and query time per minute, what happens when you go over, the headers that count them and why webhooks beat polling in a loop. - [Errors](https://safeonuba.com/en/developers/errors.md): Errors arrive as application/problem+json (RFC 9457) with the real HTTP status and a stable code to program against. - [Pagination](https://safeonuba.com/en/developers/pagination.md): Lists are paged with limit and an opaque cursor: the response includes next_cursor, which you pass back as cursor. - [Versioning](https://safeonuba.com/en/developers/versioning.md): What v1 in the path and api_version in each event mean, and the current state of the contract. - [Privacy and security](https://safeonuba.com/en/developers/privacy-and-security.md): The API sees the same as a dashboard user with those permissions. Positions only when the plant allows it, never vital signs, and every request is logged. ## More - [Changelog](https://safeonuba.com/en/developers/changelog.md): Changes to the API contract, newest first. - [Frequently asked questions](https://safeonuba.com/en/developers/faq.md): How to request access, who to contact for support and the questions that usually come up when integrating. ## Reference - [API reference](https://safeonuba.com/en/developers/reference.md): Environments and every operation at a glance. - [Authentication](https://safeonuba.com/en/developers/reference/authentication.md): OAuth2 `client_credentials`: an opaque token valid for one hour. - [Sites](https://safeonuba.com/en/developers/reference/sites.md): The client’s sites and their zones. - [Alerts](https://safeonuba.com/en/developers/reference/alerts.md): What has happened, and acknowledging or resolving it from the customer’s control room. - [Evacuations](https://safeonuba.com/en/developers/reference/evacuations.md): Status, headcount by status and by muster point, ruled-out points and who is missing. - [Workers](https://safeonuba.com/en/developers/reference/workers.md): Workers and watches. - [Positions](https://safeonuba.com/en/developers/reference/positions.md): Only those the privacy veil allows. - [Events](https://safeonuba.com/en/developers/reference/events.md): Replay the events of the last 30 days. - [Webhooks](https://safeonuba.com/en/developers/reference/webhooks.md): Destinations and the format of what is sent to them. - [Sandbox](https://safeonuba.com/en/developers/reference/sandbox.md): Test scenarios with simulated watches, so you can integrate without watches. Only on `sandbox.api.safeonuba.com`. - [Schemas](https://safeonuba.com/en/developers/reference/schemas.md): Every object in the contract, field by field. ## Contract - [OpenAPI 3.1](https://safeonuba.com/en/developers/openapi.json): the source of truth for the reference. ## Optional - [All the documentation in a single file](https://safeonuba.com/en/llms-full.txt) - [Versión en español](https://safeonuba.com/llms.txt)