Solaris.Webhooks.Handler behaviour (Solaris v1.0.0)

Behaviour for implementing a Solaris webhook event handler.

Implement this in your application to receive and process Solaris webhook events. Use Solaris.Webhooks.dispatch/2 or Solaris.Webhooks.Plug to route events to your handler.

Implementing the behaviour

defmodule MyApp.SolarisHandler do
  @behaviour Solaris.Webhooks.Handler

  @impl Solaris.Webhooks.Handler
  def handle_event("BOOKING", payload, _event) do
    booking = payload["booking"]
    MyApp.Ledger.record_booking(booking)
    :ok
  end

  @impl Solaris.Webhooks.Handler
  def handle_event("IDENTIFICATION", payload, _event) do
    person_id = payload["person_id"]
    status = get_in(payload, ["identification", "status"])

    case status do
      "successful" -> MyApp.KYC.complete(person_id)
      "failed" -> MyApp.KYC.reject(person_id)
      _ -> :ok
    end
  end

  @impl Solaris.Webhooks.Handler
  def handle_event("SCA_CHALLENGE", payload, _event) do
    MyApp.SCA.notify_user(payload)
    :ok
  end

  # Catch-all is required for forward compatibility with new event types
  @impl Solaris.Webhooks.Handler
  def handle_event(_event_type, _payload, _event), do: :ok
end

Return values

handle_event/3 should return one of:

:ok — Event processed successfully
{:ok, any()} — Same as :ok, with a result value
{:error, reason} — Processing failed; will be logged

Solaris expects a 2xx HTTP response to acknowledge receipt. The Plug returns 200 for all handler outcomes (including errors) to prevent Solaris from retrying the delivery with duplicate events.

Summary

Callbacks

handle_event(event_type, payload, event)

Called for each received webhook event.

Callbacks

handle_event(event_type, payload, event)

@callback handle_event(
  event_type :: String.t(),
  payload :: map(),
  event :: Solaris.Webhooks.event()
) :: :ok | {:ok, term()} | {:error, term()}

Called for each received webhook event.

event_type — String event name, e.g. "BOOKING", "IDENTIFICATION"
payload — Decoded JSON body as a map()
event — Full event map: %{event_type, delivery_id, payload, received_at}