# How sources work

> What a source is, how it connects, and how to read its status.

Web page: https://infrainbox.app/docs/sources/

A source is one thing that sends InfraInbox events: a Proxmox cluster, an Uptime Kuma instance, a script, a heartbeat, the InfraInbox watcher. 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

Start at **Add source** (dashboard screen `/sources/new`). 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](https://infrainbox.app/docs/sources/watcher.md) |
| Proxmox VE / Backup Server | The exact webhook configuration to paste in | [Proxmox VE and Backup Server](https://infrainbox.app/docs/sources/proxmox.md) |
| Uptime Kuma | Monitor up/down as incidents | [Uptime Kuma](https://infrainbox.app/docs/sources/uptime-kuma.md) |
| Alertmanager / Grafana | Firing and resolved alerts | [Alertmanager and Grafana](https://infrainbox.app/docs/sources/alertmanager.md) |
| Gotify-compatible | Anything that already speaks Gotify or shoutrrr | [Gotify-compatible tools](https://infrainbox.app/docs/sources/gotify-compatible.md) |
| A generic source | Any script or tool that can POST JSON | [Events API](https://infrainbox.app/docs/sources/events-api.md) |

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](https://infrainbox.app/docs/reference/event-fields.md)). It still leaked wherever the sender wrote it, so rotate it.

## How a source is wired

A source doesn't declare what feeds it — InfraInbox only reports what has actually arrived, within the last minute. Its Setup 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` | Liveness 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

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 |

> **Note:** Reachable for more than 48 hours with nothing real behind it is almost always a routing problem on the sender's side — the source's detail page calls this out directly (check the tool's matcher or notification mode, not InfraInbox's side).

**Health** — is what's behind this source actually okay right now:

| State | Meaning |
|---|---|
| Online | Its liveness monitor, if it has one, is up |
| Degraded | A job monitor is down, or an incident from this source is still open at WARNING or above |
| Offline | Its liveness monitor is down |
| Unknown | No liveness monitor is reporting — there is none, or the ones there are haven't been pinged yet or are paused |

Health only ever comes from a liveness monitor 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 [Heartbeat monitors](https://infrainbox.app/docs/sources/heartbeats.md) to close that gap.

## 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

- **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](https://infrainbox.app/docs/notifications/silences.md) narrowed to one source.
- **Rotate** a source's key from its Credentials 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 once nothing needs it. Its past incidents stay readable.

A source the [InfraInbox watcher](https://infrainbox.app/docs/sources/watcher.md) uses shows two links on its Heartbeats tab: **View watchers**, this source's own row in the [Watchers view](https://infrainbox.app/docs/start/dashboard.md), and, for an owner or admin, **Settings for every watcher of this source**, the detection-settings editor every watcher using this source's key reads from.

## Next

- [Events API](https://infrainbox.app/docs/sources/events-api.md) — the universal `curl`-first way in
- [Heartbeat monitors](https://infrainbox.app/docs/sources/heartbeats.md) — catch silence itself
- [How notifications work](https://infrainbox.app/docs/notifications.md) — what happens to an event once it arrives