OrbitsDocs
esc
    Open Orbits
    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
    NameUp to 60 characters, unique in the project, such as "Checkout slow"
    Measureerror-rate: 5xx answers as a share of requests, in %. p75 or p99: response time in milliseconds. requests: requests a minute
    Is above / Is belowThe direction. requests can be either; the others are always above
    ThresholdThe line. An error-rate threshold must be under 100
    For at leastThe window: 1, 5, 10 or 30 minutes
    RoutesThis 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 toEmail, the team webhook, or both
    The switchA 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

    1. Open the project and choose Observability.
    2. On the Alerts card, press Create alert.
    3. Pick a measure, a threshold, how long, the routes and where to send it.
    4. 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, p75 or p99) 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
    RecoveredThe value came back
    QuietIts traffic went too quiet to measure
    ChangedIt was edited while firing
    OffIt was switched off while firing
    DeletedIt 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

    Email

    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:

    1. Enter an https address on the public internet, with no user name or password in it.
    2. Save. Orbits makes a signing secret (64 hex characters) and shows it once: copy it into your receiver, for example as WEBHOOK_SECRET.
    3. Press Send test event to send a signed alert.test and 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-Eventalert.fired, alert.resolved or alert.test
    X-Delivery-IdThe same on every retry of one notice, so you can drop a repeat
    X-Signature-256sha256= and the hex HMAC-SHA256 of the raw body, keyed with the secret
    User-AgentOrbits-Alerts/1
    alert.fired
    {
      "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

    Terminal
    $ 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>
    CallWho
    GET /v1/teams/{team}/projects/{project}/alertsAny member. Rules, their state and webhook_configured
    POST .../alertsOwner, admin, member. Create a rule
    POST .../alerts/previewOwner, 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}/eventsAny member. The history
    GET /v1/teams/{team}/alert-channelsOwner, 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/testOwner, admin. Send alert.test
    POST .../alerts
    {
      "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.

    Was this page helpful?

    Updated