Alarum
smart_toy

menu_book Alarum documentation

Alarum is a centralised hub for all the events your stack fires: CI runs, cron jobs, deployments, errors, anything that can POST JSON. This guide walks through the concepts and day-to-day usage. For the developer-facing API reference, head to the Integration guide.

rocket_launch Quick start

From zero to first event in five steps:

  1. Sign in with GitHub or Codeberg from the login page.
  2. A default workspace is created automatically. Open Workspaces to add a project.
  3. Inside the project, open Settings → Tokens and create a token for your source (e.g. "GitHub Actions prod").
  4. Copy the token immediately, it's shown only once.
  5. POST your first event: 
    curl -X POST 'https://alarum.me/h' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"level":"success","title":"Hello from my script"}'

The event appears in your Inbox within seconds, and a push notification fires if you've granted permission. Need to integrate from a script, a CI pipeline, or an AI agent? The Integration guide has the full spec and copy-pasteable snippets for every common language.

Or pick yours straight from this dropdown: 

curl -X POST 'https://alarum.me/h' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"level":"success","title":"Deploy succeeded","message":"v1.2.3 shipped to production","source":"github-actions"}'

folder Workspaces & projects

Alarum organises everything in a two-level hierarchy:

  • Workspace, a group, typically representing a team, a company, or simply your personal stuff. Workspaces can be shared with other users via invitation. Each workspace has an owner and members.
  • Project, a topic within a workspace. One project per app or service is a good rule of thumb (e.g. "my-api", "backups", "monitoring"). Each project carries its own tokens, forwarders and notification rules.

To share a workspace, open it and use the invite action. Invitees receive a link they accept after signing in. They become full members and can read every event in every project of the workspace.

key Tokens

Tokens are the ingestion credentials. One token grants permission to POST events to one project's URL, that's all. They look like alrm_….

  • One token per source. Create a distinct token for each CI workflow, cron job or service, so you can revoke just the one that leaks.
  • Shown only once. The full token is revealed on creation and never again, only a prefix/suffix is stored. Lost? Revoke and create a new one.
  • Revocation is instant. Sources using a revoked token start receiving HTTP 401 immediately.
  • Per-token configuration. Each token has its own row in the project Settings, with a Configure button to override notification rules for that source specifically (more in Notifications below).

stack Events & levels

An event is a single notification posted to a token. It has a level that drives how prominently it shows up and whether you receive a push for it. Picking the right level matters more than picking a long title.

infoRoutine, informational events. No push by default to avoid noise.Push: OFF
successSomething finished successfully, a deploy, a backup, a CI run.Push: ON
warnNeeds attention but the system is still working.Push: ON
errorSomething failed, a job, a job step, a check.Push: ON
criticalUrgent failure. Can override your quiet hours.Push: ON*

* critical can bypass your quiet hours when the "critical overrides quiet hours" toggle is on (default).

Beyond the level, an event carries a title (required), an optional message, source, tags, URL, fields, timestamp, color and author. The full payload schema is documented in the Integration guide.

inbox Inbox & filters

The Inbox aggregates every event across every workspace you can see. Open a workspace or a project from the sidebar to scope the view down. New events arrive automatically, the page refreshes in the background without a visible flash, and a status dot on the Inbox icon turns yellow while a sync is in flight.

  • Filters, open the Filters drawer at the top of the inbox to narrow by level, tag, time range, or read state. Filters compose: pick multiple levels, multiple tags, etc.
  • Per-event actions, click an event to open its detail page. From there: mark as read/unread, delete (or restore a deleted event). Deleted events are hidden by default but can be revealed via the Show deleted toggle.
  • Bulk actions, use the Mark all as… dropdown to act on the entire current scope (global, current workspace, or current project).
  • Search, the search icon in the header opens a full-text search over title and message fields.

notifications Notifications & quiet hours

Push notifications are per-device and per-user. Grant permission once in your browser; Alarum remembers it via a service worker. The same account on multiple devices receives push on every device that has subscribed.

Two layers of configuration decide whether a given event triggers a push for you:

  • Project defaults, open a project's Settings; the My notifications for this project block has one toggle per level. This applies to every event in that project unless a per-token override exists.
  • Per-token override, for a noisier source, open the project's token list, click Configure on the relevant token, and switch on Override project defaults. The toggles you set apply only to events coming in through that one token.

Quiet hours mute push notifications during a time window. They're configured globally per user (Settings → Notifications) and can be overridden project-by-project. critical events can optionally bypass quiet hours via a per-quiet-hours toggle.

forward Re-forwarding to Discord, Slack, or anywhere

A forwarder is an outgoing webhook that Alarum fires when an event arrives. Three types are supported:

  • Discord, point at a Discord channel webhook URL; events are formatted as Discord embeds with the matching colour for their level.
  • Slack, point at a Slack Incoming Webhook URL; events are formatted as Slack blocks.
  • Generic, any HTTPS endpoint. Provide an optional JSON template using variables ({{level}}, {{title}}, {{message}}, etc.) and the rendered body is POSTed.

Each forwarder has a minimum level filter, set it to error and you'll only get pinged on Slack for errors and criticals. It also has a trigger scope: either all events of the project, or only events that came in via one specific token. Use scoping to send your noisy "build started" pings to a low-priority channel while reserving the urgent channel for "build failed" from the same project.

When a forwarder POST succeeds, its row shows OK ago. On failure, the error message is captured and displayed inline so you can debug.

shield Retention, account & security

Retention is tied to your plan, not to individual projects, and splits in two: a short detail history for the full raw events you can read, search and drill into from the Inbox (3 days on Discover, 30 days on Freelance, 90 days on Agency), and a much longer trend history made of lightweight daily rollups (event counts per project, day and level, plus the top tags and sources) that feeds the dashboard charts (1 month on Discover, 3 months on Freelance, 6 months on Agency). A daily cron deletes raw events older than your detail horizon, regardless of whether they were read; rollups keep your charts populated long after the raw data has aged out.

Sign-in identities. Your account can be linked to multiple OAuth providers (GitHub, Codeberg) so you can sign in with whichever is convenient. Open Settings → Profile to link or unlink a provider. Alarum will never let you unlink your last identity, that would lock you out.

Deleting your account is final. Settings → Danger zone lets you do it after typing your email to confirm. Workspaces you own, every project in them, all tokens, all forwarders and every push subscription on every device are removed in a single transaction.

help More