Before You Start

Notifications are an optional layer on top of evaluation: register one — a durable outbox entry, a NOTIFY doorbell, or a function call — against a check, a category, or globally, and the evaluation engine fires it automatically when that check's confirmed severity meets a set you choose. No polling, no separate scheduler. Firing a Notification on a Severity Change in the Adding Your Own Checks book covers the basics; this book is the full reference — every parameter, the exact firing rule, wiring your own delivery, the whole lifecycle, and how to debug one that isn't behaving as you expected.

This is entirely opt-in. A check with no notifications registered behaves exactly as it did before — nothing about collection, evaluation, or severity computation changes.

The one prerequisite: a check that produces a severity

A notification watches confirmed severity, so it only ever fires for a check that actually gets evaluated against a threshold (or a custom evaluator). A check that only ever collects — never evaluated, or with no threshold — produces no severity, so nothing fires. If a notification never fires, this is the first thing to confirm (see Troubleshooting).

The two choices you make

Every notification is defined by two orthogonal choices, covered in full in the next chapters:

• trigger_mode — on_change (fire on a transition into/out of your severity set — for persistent, polled conditions) or on_state (fire on every in-set evaluation — for on-event checks and "nag" reminders, optionally throttled by a cooldown).
• delivery_kind — outbox, notify (a standard PostgreSQL NOTIFY), pg_relay_notify (a pg_relay enqueue — requires the pg_relay extension), or function. Every firing lands in the one durable outbox pghf.notification_log first; delivery is layered on top, so your own delivery system and the optional pg_relay_notifier both wire into a single place.

Continue to Creating a Notification.