How sources work
A source is the app, host or cluster you want alerts about — a Proxmox cluster, an Uptime Kuma instance, a Docker host, a script. The tools that report on it (a heartbeat, the InfraInbox watcher, a webhook) are wired into it, not sources of their own. Every source belongs to one workspace, and every event it sends is scoped to that workspace — the source’s credential decides which workspace, never the request itself.
Adding one
Section titled “Adding one”Start at Add source. The picker offers:
| Entry | What it’s for | Guide |
|---|---|---|
| InfraInbox watcher | Docker on one host: container health plus a host heartbeat | Docker and host watcher |
| Proxmox VE / Backup Server | The exact webhook configuration to paste in | Proxmox VE and Backup Server |
| Uptime Kuma | Monitor up/down as incidents | Uptime Kuma |
| Alertmanager / Grafana | Firing and resolved alerts | Alertmanager and Grafana |
| Gotify-compatible | Anything that already speaks Gotify or shoutrrr | Gotify-compatible tools |
| Pulse | Pulse’s alerts as incidents, closed when Pulse resolves them | Pulse |
| Dozzle | Dozzle’s log, metric and container alerts | Dozzle |
| NetAlertX | Devices down, back and new on your network | NetAlertX |
| Checkmate | Monitor down/up and threshold breaches as incidents | Checkmate |
| WUD | Container image updates, as notices | WUD (What’s up Docker) |
| A generic source | Any script or tool that can POST JSON | Events API |
Every source gets its own credential the moment it’s created, shown once: an ingest key shaped like iik_src_…. Keep it — InfraInbox stores only a hash of it and can’t show it to you again; if you lose it, rotate it instead.
A key that ends up inside an event’s own text, for example in a cron job’s mail subject, is removed before the event is stored (event fields). It still leaked wherever the sender wrote it, so rotate it.
The Sources list
Section titled “The Sources list”Sources has two tabs, each with its count and its own address: Sources (/sources) and Watchers (/sources/watchers, the hosts running the InfraInbox watcher).
Each row of the Sources tab is one source, and the whole row opens it (click it, or Tab to its name and press Enter). The columns:
- Source: its name and kind: the tool it speaks for, or InfraInbox watcher · 2 hosts for a source a watcher is attached to.
- Status: one chip, the same word its own page’s header uses — Offline or Degraded (with why, in short) when a check needs attention, Receiving (a request arrived in the last 24 hours), Idle (it was receiving and has since gone quiet) or Waiting for first request (nothing has arrived yet) — plus its own Muted chip beside it when a mute is holding notices back. Muting never hides the state: a muted source that’s Offline still says so.
- Checks: how many checks watch it, one per watcher host plus its ping checks (2 watchers, 3 checks), and the worst of them (all OK, 1 down, 1 late, 1 not reporting).
On a phone, each source is a two-line card: its name and kind beside its status, then its checks and its last request.
- Who’s told: Default, or the name of the rule for some sources that handles it.
- Last request: when it last sent anything (a Test or a ping counts too).
Find a source searches names and kinds; Status and Kind narrow the list — picking Needs attention matches every source whose chip reads Offline or Degraded (an open incident can cause a Degraded, not only a late check), and Muted matches every muted source regardless of its state. All three stay in the address, so Back and a shared link keep them. A search looks through the first 200 sources. The list has no mute or delete of its own: both are on the source’s own page, so a stray click on the list only ever opens something.
A source’s page
Section titled “A source’s page”A source’s page is where everything about it lives, in five tabs:
| Tab | Holds |
|---|---|
| Overview | How it’s set up, in one strip — 1 · Comes in (how it’s wired), 2 · Decided by (its built-in rules, and your rules that name it), 3 · Tells (the row of Everything else that handles it, and who that is), each linking to the tab that changes it. It’s the configuration, not a trace of something that happened. Below it: its open incidents, its checks and how it stands. An owner or admin also gets Preview routing for [name], opening Preview routing on a sample from this source. |
| Connect | What feeds it, the setup guide for its tool — the same steps you saw when you created it, with a placeholder where the key goes — and its keys (owner or admin), with one Create an ingest key button. Key rotation, troubleshooting and keys in a URL are folded until you open them. |
| Checks | What notices when it goes quiet, summarised in one line at the top: ping checks and watchers, each check listed once. |
| Notifications | Who hears about it: its recipients, Default’s behavior, custom and built-in rules, with a live preview. See below. |
| Events | Its own events and, for an owner or admin, the raw requests it sent. |
Each tab has its own address (/sources/<id>/checks, and so on), so Back and a shared link land on the same tab, and the Events tab keeps its sort and page. A member sees the same five tabs, read-only, without the keys and the raw requests. An event opened from the Events tab opens in a panel on the right, with its message and metadata and a link to its own page; an incident opened from a source comes back to it through the breadcrumb.
Under the name, one chip says how the source stands — Receiving events, Idle once it’s gone quiet a day (the same rule the Sources list uses, so the two never disagree), or Offline and Degraded when that matters more — with a plain add a heartbeat note beside it once the first event has arrived and nothing would notice the source going quiet (a job check alone doesn’t count: only a heartbeat clears it); then what it is: its tool, or InfraInbox watcher. Before anything has arrived, Comes in on the Overview strip reads Continue [tool] setup rather than asking you to pick one again — the tool was already chosen when the source was created. The Overview’s checks card lists each watcher host (Watcher · checked in 3m ago, Reporting or Stale) before the ping checks, and a watcher counts once, not again for the heartbeat it pings — the same is true of the Checks tab’s own summary line. The Connect tab leads with the ways in use and folds the rest under Other tools that can report on it.
How a source is wired
Section titled “How a source is wired”A source doesn’t declare what feeds it — InfraInbox reports only what has actually arrived, within the last minute. Its Connect tab lists up to four wiring kinds:
| Kind | Carries |
|---|---|
api |
Anything posting JSON straight to the Events API |
webhook |
A tool’s own adapter (Proxmox, Uptime Kuma, Alertmanager/Grafana) |
gotify |
A Gotify-compatible sender |
heartbeat |
Host or job pings |
Each row reads Receiving once traffic has arrived on it, or Idle otherwise — never “configured”, because a wiring you set up but never used would be honestly idle either way.
Status: two independent readings
Section titled “Status: two independent readings”Every source shows two things, and they answer different questions.
Connection — is anything reaching this source at all:
| State | Meaning |
|---|---|
| Waiting for first request | Nothing has arrived yet |
| Reachable | A test or a tool’s own “Test” button got through, but no real event has |
| Receiving events | At least one real event has arrived |
| Unknown | Not yet determined |
Health — is what’s behind this source actually okay right now:
| State | Meaning |
|---|---|
| Online | Its heartbeat, if it has one, is up |
| Degraded | A ping check is down, or an incident from this source is still open at WARNING or above |
| Offline | Its heartbeat is down |
| Unknown | No heartbeat is reporting — there is none, or the ones there are haven’t been pinged yet or are paused |
Health only ever comes from a heartbeat or an open incident — never from silence. A source that has gone quiet reads Unknown, not Offline, unless something is actually watching for that silence. See Heartbeats and ping checks to close that gap.
Degraded says why, right beside the chip: whichever of its two causes is known, an open incident (naming it, and linking to it) or a job check that’s down (naming it, and linking to the Checks tab). When neither has loaded yet, it falls back to naming both possible causes at once.
Testing a source
Section titled “Testing a source”Every source has a Send test action (owner or admin). It fires one synthetic test event through the same path a real one takes, skipping rules, silences and incident correlation, and marks the source Reachable. It queues one test notice to every enabled destination, so it’s also how you check a Telegram chat or a webhook actually receives something. A tool’s own “Test” button, where it has one (Proxmox, Uptime Kuma), calls this exact path from the tool’s side.
Muting, rotating, deleting
Section titled “Muting, rotating, deleting”- Mute a source (from its detail page) to hold back its notices without losing anything: events still arrive, incidents still open, only the alerts stop. A mute is a silence narrowed to one source.
- Route a source differently from the rest: its Notifications tab’s Recipients puts it on a rule for some sources, which replaces who Default tells for it (Telegram only and no push, say). Such a source shows that rule’s name on the Sources list.
- Rotate a source’s key from its Connect tab if it may have leaked. The old key keeps working for 24 hours, so you have time to update the sender before it stops.
- Delete a source from the ⋯ menu on its page (beside Rename) once nothing needs it. The confirmation says what goes with it: its keys, its open incidents (resolved), its watchers and its ping checks. Its past incidents stay readable.
Who hears about a source
Section titled “Who hears about a source”A source’s Notifications tab answers “who is told, and why”, in Routing’s order: this source’s recipients and Default’s behavior first, custom and built-in rules after. Events are still checked custom rules first, then built-in rules, then Default:
- Recipients: which row handles it. Handled by switches between Default and a rule for some sources, which replaces who Default tells for it (Telegram only and no push, say); the switch says so with Undo. Change recipients opens a rule like Default, but tell… for this source in a side panel and puts the source on it. No push and Silent speak only for this rule’s recipients: custom rules, and a built-in rule with a destination of its own, can still notify. A built-in rule that still reaches your default destinations is named right there, unless the rule also covers built-in alerts. A source on such a rule shows its name beside its own.
- Default behavior: Default’s table (Severity · In InfraInbox · Notify), with this source’s own recipients in Notify where Default tells anyone, and Edit default behavior.
- Custom rules: your rules that name it, as sentences, each opening the rule; Create a custom rule opens a new one with the source condition already filled in, and brings you back here after the save. Below them, the workspace’s rules that name no source at all are listed as candidates only — some other field might still match this source, so Preview (below) is how you check which one actually does.
- Built-in rules for its integration: edited right here: Use the workspace’s built-in rules, or Customize for this source to edit a copy of its own with the save bar. Going back to the workspace’s built-in rules deletes that copy, with Undo. An integration that ships no built-in rules says Not used.
The Preview beside the sections runs a chosen event from this source down the list — a plain one, the integration’s example, or one of the source’s own recent events (fixed at its own severity) — at the severity you pick, and shows which section decided and who would be told. Nothing is sent.
Seeing the raw requests
Section titled “Seeing the raw requests”The Events tab’s Raw requests (owner or admin) lists the last 20 requests a source sent, with secrets stripped and bodies cut at 64 KB. Keep the requests this source sends turns capture on or off for that source. Turning it off stops storing new requests; what is already stored stays until you Purge now, beside the switch. A JSON body is shown indented.
A source the InfraInbox watcher uses lists its watchers on its Checks tab, each opening the watcher’s page, and, for an owner or admin, Watcher settings for the source, the detection-settings editor every watcher using this source’s key reads from. All hosts are on the Sources page’s Watchers tab.
- Events API — the universal
curl-first way in - Heartbeats and ping checks — catch silence itself
- How notifications work — what happens to an event once it arrives