Sending alerts

An alert is one POST to /notify with a JSON body. This page is the full contract for that request. To attach images, see Images; for checklists, see Checklists.

POST https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify

Header names are case-insensitive. Only POST is accepted; any other method returns 405 METHOD_NOT_ALLOWED.

{
  "title": "Build complete",
  "body": "The release build finished successfully.",
  "category": "build",
  "severity": "high",
  "todo": ["Tag the release", "Post the notes"],
  "data": {
    "buildId": "2026.07.26.14",
    "branch": "main",
    "durationSeconds": 482
  }
}

The whole JSON body is limited to 16 KiB; a larger body returns 413 PAYLOAD_TOO_LARGE. A field that breaks a rule returns 400 INVALID_PAYLOAD.

Zona also caps the push it generates at a conservative 3,800 UTF-8 bytes. Text that uses several bytes per character, such as Chinese or emoji, can therefore return 400 INVALID_PAYLOAD before it reaches the character limits above. If that happens, shorten the title and body.

Severity is optional presentation. It changes how the alert looks, not how it is delivered: it does not affect delivery priority, sound, rate limits or which source the alert belongs to.

The ring shows on the inbox row, on the alert’s details, which also name the level, and on the banner Zona shows while it is open. It is thicker for more urgent levels, so the level reads without relying on colour. While the alert is unread the ring pulses, faster for more urgent levels; once you have read it, or with Reduce Motion on, the ring stays still. Its colours are the system green, yellow, orange and red for the active theme’s light or dark appearance.

On iPhone, iOS controls the icon in a system notification, so a lock-screen or system banner does not show the severity colour. It appears once you are in Zona.

The operator can temporarily switch off critical alerts. While that switch is off, a critical request returns 403 CRITICAL_SEVERITY_DISABLED. Only send a lower severity instead if it still describes the event honestly.

Severity is part of the payload for idempotency: resending a key with only the severity changed returns 409 IDEMPOTENCY_CONFLICT.

category is a free-form label such as backup, build or deploy. It groups and describes alerts; it does not choose a sound. Each source’s sound is set in the app.

data carries context for your own tooling, such as a build ID, a branch or a job name. Zona stores it with the inbox item. It does not change routing, source identity, sound, severity or push behaviour.

• Use namespaced, non-sensitive keys.
• Keep large logs and files elsewhere, and link to them.
• Never put tokens, passwords or secrets in data. Like the title and body, it can reach the phone.

curl --request POST \
  "https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify" \
  --header "Authorization: Bearer $ZONA_SOURCE_TOKEN" \
  --header "Idempotency-Key: build-20260726-14" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Build complete",
    "body": "The release build finished successfully.",
    "category": "build",
    "severity": "high",
    "data": {"buildId": "2026.07.26.14", "branch": "main"}
  }'

$headers = @{
  Authorization = "Bearer $env:ZONA_SOURCE_TOKEN"
  'Idempotency-Key' = 'deploy-' + [guid]::NewGuid().ToString()
}
$payload = @{
  title = 'Deployment complete'
  body = 'Version 1.2.0 is online.'
  category = 'deploy'
  severity = 'medium'
  data = @{ version = '1.2.0'; environment = 'production' }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Method Post `
  -Uri 'https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify' `
  -Headers $headers `
  -ContentType 'application/json; charset=utf-8' `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($payload)) `
  -TimeoutSec 10

import os
import uuid

import requests

response = requests.post(
    "https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify",
    headers={
        "Authorization": f"Bearer {os.environ['ZONA_SOURCE_TOKEN']}",
        "Idempotency-Key": f"export-{uuid.uuid4()}",
    },
    json={
        "title": "Job complete",
        "body": "The data export is ready.",
        "category": "export",
        "data": {"jobId": "export-1842", "rows": 12500},
    },
    timeout=10,
)
response.raise_for_status()
print(response.json()["notificationId"])

const response = await fetch('https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.ZONA_SOURCE_TOKEN}`,
    'idempotency-key': `health-${crypto.randomUUID()}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Service recovered',
    body: 'The API health check is passing again.',
    category: 'health',
    severity: 'low',
    data: { service: 'orders-api', status: 'healthy' },
  }),
  signal: AbortSignal.timeout(10_000),
});

const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error}`);
console.log(result.notificationId);

These examples mint a fresh key each run, which is fine for a one-off send. A job that retries should create its key once per event and reuse it; see Idempotency and retries.

A newly accepted alert returns 202. An identical replay of an earlier request returns 200 with the original record.

Errors use a small envelope, {"error": "INVALID_TOKEN"}. Every code is listed in Errors and limits.

These live in the app and are deliberately out of reach of a request: