@spec configure(
  map(),
  keyword()
) :: {:ok, Railsr.Types.WebhookConfig.t()} | {:error, Railsr.Error.t()}

Create or update the webhook endpoint configuration.

Params

• :url — HTTPS endpoint URL (required)
• :secret — HMAC signing secret; store securely and rotate regularly

@spec event_types() :: [String.t()]

Returns the full list of Railsr webhook event type strings.

@spec get_config(keyword()) ::
  {:ok, Railsr.Types.WebhookConfig.t()} | {:error, Railsr.Error.t()}

Get the current webhook configuration (secret is never returned by Railsr).

@spec list_history(
  map(),
  keyword()
) :: {:ok, [Railsr.Types.WebhookEvent.t()]} | {:error, Railsr.Error.t()}

Retrieve webhook delivery history (up to 90 days).

Query params

• :from / :to — ISO 8601 datetimes (required; max 7-day window)
• :type — filter by event type string

• :status — "delivered" | "failed" | "pending"

• :limit / :offset

@spec parse_event(map()) :: {:ok, Railsr.Types.WebhookEvent.t()}

Parse an incoming webhook event payload map into a WebhookEvent struct.

@spec retry(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.WebhookEvent.t()} | {:error, Railsr.Error.t()}

Retry delivery of a specific notification by ID.

@spec verify_signature(binary(), String.t() | nil, String.t()) ::
  :ok | {:error, :invalid_signature}

Verify the HMAC-SHA256 signature on an incoming Railsr webhook payload.

Railsr signs each delivery with HMAC-SHA256(secret, raw_body) and sends the hex digest in the X-Railsr-Signature header.

Usage in a Phoenix controller

def railsr_webhook(conn, _params) do
  raw_body = conn.assigns[:raw_body]
  signature = get_req_header(conn, "x-railsr-signature") |> List.first()
  secret = Application.get_env(:myapp, :railsr_webhook_secret)

  case Railsr.Resources.Webhooks.verify_signature(raw_body, signature, secret) do
    :ok ->
      event = Jason.decode!(raw_body)
      MyApp.Events.handle(event)
      send_resp(conn, 200, "ok")

    {:error, :invalid_signature} ->
      send_resp(conn, 401, "invalid signature")
  end
end