Verifies Ramp webhook signatures and decodes webhook payloads into Ramp.Webhooks.Event structs.

Ramp signs each webhook delivery with HMAC-SHA256 over the raw request body, sent in the X-Webhook-Signature header, alongside a timestamp in X-Webhook-Timestamp that lets you additionally guard against replay of captured deliveries.

Always verify against the raw, unparsed request body -- reserializing JSON can change byte-for-byte formatting and break the signature check. In a Phoenix app, read the raw body before your JSON parser plug runs (e.g. with a custom Plug.Parsers body reader), or read it directly with Plug.Conn.read_body/2 in a plug placed ahead of Plug.Parsers.

Example (Plug/Phoenix controller)

def webhook(conn, _params) do
  {:ok, raw_body, conn} = Plug.Conn.read_body(conn)
  signature = conn |> Plug.Conn.get_req_header("x-webhook-signature") |> List.first()
  timestamp = conn |> Plug.Conn.get_req_header("x-webhook-timestamp") |> List.first()

  case Ramp.Webhooks.construct_event(raw_body, signature, timestamp, @webhook_secret) do
    {:ok, event} ->
      MyApp.WebhookProcessor.handle(event)
      send_resp(conn, 200, "ok")

    {:error, %Ramp.Error{}} ->
      send_resp(conn, 400, "invalid signature")
  end
end