ObserveAlerts
Alerts
Be told when production's error rate or response times cross a line you choose, or when its traffic stops. Rules are checked every minute, and fired and resolved notices go by email or to your team's signed webhook.
What an alert watches
An alert rule belongs to a project and watches production: the same requests as Observability. Previews are never measured. Each rule has:
| Field | |
|---|---|
| Name | Up to 60 characters, unique in the project, such as "Checkout slow" |
| Measure | error-rate: 5xx answers as a share of requests, in %. p75 or p99: response time in milliseconds. requests: requests a minute |
| Is above / Is below | The direction. requests can be either; the others are always above |
| Threshold | The line. An error-rate threshold must be under 100 |
| For at least | The window: 1, 5, 10 or 30 minutes |
| Routes | This project (every route) or These routes: up to 10 routes as Observability names them, a trailing * for a prefix, such as /checkout, /api/checkout/* |
| Send to | Email, the team webhook, or both |
| The switch | A rule that's off isn't checked |
"Requests below 1 a minute for 10 minutes" is how you find out production stopped getting traffic. "Requests above" catches a spike.
Create one
- Open the project and choose Observability.
- On the Alerts card, press Create alert.
- Pick a measure, a threshold, how long, the routes and where to send it.
- Press Create alert.
The rule starts as OK and is first checked at the next :30 past the minute. Owners, admins and members create, edit, switch and delete rules; viewers see them but can't change them.
The traffic warning
error-rate, p75 and p99 need at least 20 requests in a window before they say anything: one failure out of two requests isn't a 50% error rate worth waking someone for. While you fill in the form, Orbits looks at the last 24 hours and warns when your routes don't get that much, for example:
These routes get about 6 requests in 1 minute. The rule won't fire until a window has 20. Try 5 or 10 minutes.
It's a warning, not a refusal: you can still save the rule, and it works once traffic grows. requests rules have no minimum.
How rules are checked
Every minute, at 30 seconds past, Orbits works each rule's measure out over its window, ending at the last whole minute.
- Fired: when the value is past the line (above the threshold, or below it for a "below" rule), the rule goes from OK to Firing and its channels are told once.
- Resolved: after 3 checks in a row back on the right side of the line (or at it), it goes back to OK and its channels are told it resolved. This stops a value hovering at the line from firing every minute. A 30-minute rule resolves later, since its window holds on to the failure for a while.
- No repeats while it stays firing.
- Too little traffic (under 20 requests for
error-rate,p75orp99) means the rule can neither fire nor resolve on that check. A firing rule still counts such a quiet check towards resolving, unless the few requests there were are still past the line. A rule that resolves this way says its traffic went too quiet to measure. - If Orbits can't read the logs for a minute, that minute is skipped and nothing changes. "Below" rules are also skipped when no logs have arrived from anywhere lately, so a delay on Orbits' side doesn't set them all off.
Editing, switching off or deleting a firing rule resolves it first, so a receiver that opened an incident sees it close. Any change starts the rule again from OK.
History
Each rule's history lists when it fired and resolved, newest first, kept for 90 days. A resolve says why:
| Reason | |
|---|---|
| Recovered | The value came back |
| Quiet | Its traffic went too quiet to measure |
| Changed | It was edited while firing |
| Off | It was switched off while firing |
| Deleted | It was deleted while firing |
Each event also shows how every channel's notice went: still trying, delivered, or failed with the reason ("The webhook answered 500"). A notice is tried up to 5 times over about 30 minutes before it's marked failed. Deleting a rule deletes its history.
A fired or resolved alert is also a line in the team's activity feed, and a firing alert shows in the bell.
Channels
To the team's owners, admins and members, the people who deploy. Viewers don't get alert email. There is no per-person opt-out yet.
The team webhook
One webhook per team, used by every rule that has Team webhook in Send to, from every project. Owners and admins set it under Team › Settings › Alert webhook; members and viewers can't see its address, only whether one is set. A rule can't pick the webhook until the team has one.
To set it up:
- Enter an
httpsaddress on the public internet, with no user name or password in it. - Save. Orbits makes a signing secret (64 hex characters) and shows it once: copy it into your receiver, for example as
WEBHOOK_SECRET. - Press Send test event to send a signed
alert.testand see whether it was delivered, or what the receiver answered.
Rotate secret makes a new one, shown once; the old one stops working at once, so update your receiver straight after. Remove webhook stops sending: notices still waiting fail with "The team has no webhook".
Alerts can't go to Slack or Microsoft Teams yet; use email or the webhook.
What the webhook receives
Each notice is a JSON POST with these headers:
| Header | |
|---|---|
X-Orbits-Event | alert.fired, alert.resolved or alert.test |
X-Delivery-Id | The same on every retry of one notice, so you can drop a repeat |
X-Signature-256 | sha256= and the hex HMAC-SHA256 of the raw body, keyed with the secret |
User-Agent | Orbits-Alerts/1 |
{
"type": "alert.fired",
"delivery_id": "adl_…",
"event_id": "…",
"at": "2026-11-10T09:15:30Z",
"reason": null,
"value": 8,
"summary": "8% errors over 5 minutes",
"measure": { "requests": 250, "errors": 20 },
"rule": {
"id": "alr_…", "name": "Checkout errors", "metric": "error-rate", "direction": "above",
"threshold": 5, "window_minutes": 5, "routes": ["/checkout", "/api/checkout/*"]
},
"project": { "id": "prj_…", "slug": "storefront", "name": "Storefront" },
"team": { "id": "team_…", "slug": "acme" },
"url": "https://orbits.africa/…/observability"
}alert.resolved has the same shape with a reason. alert.test carries only type, delivery_id, at and team. url links to the project's Observability page.
Answer with any 2xx and the notice is delivered. Anything else, or no answer within 10 seconds, is tried again. Redirects aren't followed, and an address that isn't on the public internet is refused.
Check the signature before trusting a request. The webhooks of Integrations are signed the same way, and that page has verification code for Node and Python.
From the CLI and the API
$ orbits alerts create "Errors" --metric error-rate --threshold 5 --window 5$ orbits alerts create "Quiet" --metric requests --direction below --threshold 10 --window 30$ orbits alerts ls$ orbits alerts disable <alert id>$ orbits alerts events <alert id>| Call | Who |
|---|---|
GET /v1/teams/{team}/projects/{project}/alerts | Any member. Rules, their state and webhook_configured |
POST .../alerts | Owner, admin, member. Create a rule |
POST .../alerts/preview | Owner, admin, member. The traffic a draft rule would see: median_requests, minimum_requests, value |
PATCH .../alerts/{alert}, DELETE .../alerts/{alert} | Owner, admin, member |
GET .../alerts/{alert}/events | Any member. The history |
GET /v1/teams/{team}/alert-channels | Owner, admin. The webhook's address and the secret's last four characters |
PUT .../alert-channels/webhook, DELETE ... | Owner, admin. Set (rotate_secret: true for a new secret) or remove it |
POST .../alert-channels/webhook/test | Owner, admin. Send alert.test |
{
"name": "No traffic",
"metric": "requests",
"direction": "below",
"threshold": 1,
"window_minutes": 10,
"routes": [],
"channels": ["email", "webhook"]
}A 422 names the field that's wrong. The full reference is at API › Alerts.