Lithic.Webhook (Lithic v1.0.0)

Webhook signature verification for Lithic webhooks.

Lithic signs webhook payloads with HMAC-SHA256. This module provides verification for all Lithic webhook types:

Event subscriptions
Auth Stream Access (ASA)
Tokenization Decisioning
3DS Decisioning

Usage

# Plug/Phoenix controller
def handle_webhook(conn, _params) do
  raw_body = conn.assigns[:raw_body]
  signature = get_req_header(conn, "webhook-signature") |> List.first()
  timestamp  = get_req_header(conn, "webhook-timestamp") |> List.first()

  case Lithic.Webhook.verify(raw_body, signature, timestamp, secret: "whsec_...") do
    {:ok, payload} ->
      process_event(payload["type"], payload)
      send_resp(conn, 200, "ok")

    {:error, reason} ->
      send_resp(conn, 400, reason)
  end
end

Summary

Functions

verify(body, signature, timestamp, opts)

Verify a Lithic webhook payload.

verify!(body, signature, timestamp, opts)

Verify without timestamp tolerance checking (e.g. during replay tests).

Functions

verify(body, signature, timestamp, opts)

@spec verify(binary(), String.t() | nil, String.t() | nil, keyword()) ::
  {:ok, map()} | {:error, String.t()}

Verify a Lithic webhook payload.

Accepts:

body — raw binary request body (not decoded)
signature — webhook-signature header value (e.g. "v1,base64sig")
timestamp — webhook-timestamp header value (unix seconds as string)
opts — [secret: "whsec_..."]

Returns {:ok, decoded_payload} or {:error, reason}.

verify!(body, signature, timestamp, opts)

@spec verify!(binary(), String.t(), String.t(), keyword()) :: map()

Verify without timestamp tolerance checking (e.g. during replay tests).