The behaviour contract for a Raven alert handler.

A handler watches the DataBus for monitor status events and decides when to fire. When it fires, the platform calls every channel in the handler's config. Handlers run as supervised GenServer processes — one process per configured handler instance — giving them persistent state across events.

This is the last piece of the alerting stack:

Monitor → DataBus → Handler → Channel

Monitors publish health signals. Handlers react to those signals. Channels deliver the notification.

Implementing a handler

defmodule MyHandlers.OnDown do
  use CodeNameRaven.Handler

  @impl true
  def handler_init(_params), do: {:ok, %{}}

  @impl true
  def on_status(%{status: :down} = msg, _params, state) do
    notification = %Notification{
      monitor_id:      msg.monitor_id,
      status:          :down,
      previous_status: nil,
      occurred_at:     msg.checked_at
    }
    {:fire, notification, state}
  end

  def on_status(_msg, _params, state), do: {:ok, state}
end

on_status/3 is the only required callback — everything else has a working default.

Return values from on_status/3

• {:ok, new_state} — no alert; update state and wait for the next event.
• {:fire, notification, new_state} — deliver notification to every channel in this handler's config, then update state.

The status argument

on_status/3's first argument is loosely typed (term()) rather than a concrete struct — the real message module (and its version/upcast machinery) lives in Raven itself, not this SDK, matching CodeNameRaven.Probe.on_metric/3's precedent for the identical problem. It has (at least) these fields: monitor_id (string), status (:up | :degraded | :down | :unknown), checked_at (DateTime.t()), node (the reporting node, or nil/:nonode@nohost for a local-only signal). Raven upcasts the message to its current version before this callback ever sees it, so implementations never need to think about version compatibility themselves — pattern-match on the fields you need with a plain map pattern (it matches the real struct too, since structs are maps) rather than a named struct.

State

handler_state is opaque to the platform. Use it to track whatever the handler needs between events: the last known status per monitor, cooldown timers, deduplication keys. The state is ephemeral — a handler restart resets it via handler_init/1.