Skip to content

Pinggy

Notification channels

Delivering a confirmed incident to a notification channel, and delivery retries.

Two channel types

A confirmed incident is delivered to the notification channels a tenant has configured. Pinggy supports two channel types:

  • ntfy — a server URL (any self-hosted host is supported), a topic, a priority from 1 through 5, and an optional access token.
  • Generic webhook — an HTTPS endpoint, an optional HMAC signing secret, and up to five custom headers.

A channel subscribes to one or more event types: monitor.down, monitor.recovered, node.offline, and node.recovered.

Destination rules

Both channel types are validated by the same rules. A destination must be HTTPS — a notification carries incident evidence and, for webhooks, an HMAC signature, and neither belongs on an unencrypted connection. A destination may not embed credentials, a fragment, control characters, an invalid port, or a malformed address, and is bounded at 2048 characters. An internal or private destination is not blocked on its own: this is a self-hosted deployment trusted to reach its own network, and only Owners and Admins can configure a channel in the first place.

Custom headers

A webhook channel may carry up to five custom headers: names limited to lower-case letters, digits, hyphen, and underscore; values limited to printable ASCII. A reserved-name list refuses headers that would collide with authorization, cookie, host, content-length, content-type, hop-by-hop headers, or the namespace Pinggy's own signature and delivery-ID headers use.

Secrets

An access token, a signing secret, and every custom header value are sealed at rest under the application's master key and are never returned by the API, never rendered in a template, and never logged. A channel's API representation states only whether a secret is present, not its value. Losing the master key does not stop monitoring or incident confirmation — it disables exactly the actions that need to seal or open a secret, and fails closed rather than exposing or guessing at a value it cannot verify.

Durable delivery

Delivery runs through a transactional outbox: a notification is recorded in the same transaction as the event that caused it, then delivered by a separate worker with retries and bounded backoff. A delivery that keeps failing is retried a bounded number of times and then recorded as failed rather than retried forever; an operator can see delivery history and retry one manually from the deliveries screen.

Testing a channel

A channel's test action sends a bounded, rate-limited test event and proves the channel's secrets can still be opened — it does not simulate a real incident, and it is itself audited.

This article is part of this repository and is served by the same binary, so what you read here is the documentation for the version you are running.