Alerts

An alert is something that has happened in the plant and that someone has to deal with: an SOS, a fall, someone entering where they shouldn’t, a watch with a flat battery or an earthquake warning. It’s the central object of the API.

The object#

The alert arrives complete in every webhook (data.alert) and is what GET /v1/alerts/{id} returns. The most commonly used fields:

The full list, field by field, is in the schema Alert.

Types#

A nearby vehicle is not an alert#

Nearby-vehicle warnings don’t generate alerts of their own. They go inside the alert for an incident, in two lists:

• nearby: who was within 100 metres when a critical alert (SOS or fall) was raised, people or vehicles. It gives the distance, never the position, and doesn’t count anyone who was in a privacy zone.
• vehicle_warnings: the nearby-vehicle warnings that person received in the incident window, with the distance and whether they saw them on the watch.

Details for each type#

details changes according to type. For example, SosDetails says how the SOS was raised (trigger), ZoneDetails carries the permit to work that applied (permit_reference) and HazardDetails the magnitude, the distance and whether the warning is official. The variants are in AlertDetails.

Severity#

The severity filter of GET /v1/alerts and the min_severity of webhooks are minimums: high returns high and critical.

States#

• Acknowledging assigns the alert to whoever acknowledges it, if nobody was handling it. Acknowledging is not resolving: an acknowledged alert keeps marking the person on the map until it is resolved.
• Resolving records who, when and with what note, in resolved.
• A resolved alert can be reopened. The alert.reopened event announces it.

Acknowledging and resolving from your control room#

PUT /v1/alerts/{id} with the alerts:write scope. The body:

The operator is required because “acknowledged” measures a person’s response. In the alert’s timeline it appears as “Customer · Operator (via integration)”.

curl -X PUT https://sandbox.api.safeonuba.com/v1/alerts/0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90 \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "resolution_reason": "False alarm",
    "note": "Confirmed by radio with the supervisor.",
    "actor": { "name": "E. Example", "external_id": "OP-117" }
  }'

const res = await fetch(`https://sandbox.api.safeonuba.com/v1/alerts/${alertId}`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${await safeOnubaToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 'resolved',
    resolution_reason: 'False alarm',
    note: 'Confirmed by radio with the supervisor.',
    actor: { name: currentOperator.name, external_id: currentOperator.id },
  }),
});
if (res.status === 409) {
  // It was already resolved, or the transition isn't possible: nothing to do.
} else if (!res.ok) {
  throw new Error(`${res.status}: ${await res.text()}`);
}

res = requests.put(
    f"https://sandbox.api.safeonuba.com/v1/alerts/{alert_id}",
    headers={"Authorization": f"Bearer {safeonuba_token()}"},
    json={
        "status": "resolved",
        "resolution_reason": "False alarm",
        "note": "Confirmed by radio with the supervisor.",
        "actor": {"name": current_operator.name, "external_id": current_operator.id},
    },
    timeout=10,
)
if res.status_code != 409:  # 409: it was already resolved
    res.raise_for_status()

var body = JsonContent.Create(new
{
    status = "resolved",
    resolution_reason = "False alarm",
    note = "Confirmed by radio with the supervisor.",
    actor = new { name = currentOperator.Name, external_id = currentOperator.Id },
});
var res = await http.PutAsync($"https://sandbox.api.safeonuba.com/v1/alerts/{alertId}", body);
if (res.StatusCode != System.Net.HttpStatusCode.Conflict) res.EnsureSuccessStatusCode();

The response is the updated alert. If the transition isn’t possible —for example, resolving or acknowledging an alert that is already resolved— the API responds 409.

Querying alerts#

GET /v1/alerts returns alerts from newest to oldest, paginated. Filters:

To follow alerts in real time, don’t poll in a loop: use webhooks. The list is for loading the state at start-up and for searching.

Worker names#

Names are optional by contract. If your contract doesn’t include them, worker.name doesn’t appear and title is built from the type, the zone and the company identifier (external_id), without a name. See Workers and watches.