Wise.Services.Webhooks (Wise v1.0.0)

Wise Webhook API — subscription management and signature verification.

Signature Verification

def handle_webhook(conn) do
  body = conn.body_params |> Jason.encode!()
  sig  = get_req_header(conn, "x-signature-sha256") |> List.first()

  case Wise.Services.Webhooks.verify_signature(body, sig, secret) do
    :ok    -> dispatch(body)
    :error -> conn |> put_status(401) |> halt()
  end
end

Summary

Functions

create(config, attrs)

Creates a webhook subscription.

delete(config, profile_id, sub_id)

Deletes a webhook subscription.

get(config, profile_id, sub_id)

Fetches a webhook subscription by ID.

list(config, profile_id)

Lists all webhook subscriptions for a profile.

parse_event(body)

Parses a raw JSON webhook body into a map. Returns {:ok, event_map} or {:error, reason}.

test(config, sub_id)

Triggers a test delivery for a subscription.

verify_and_parse(body, signature_header, secret)

Verifies and parses a webhook payload in one call. Returns {:ok, event_map} or {:error, Error.t()}.

verify_signature(body, signature_header, secret)

Verifies the HMAC-SHA256 signature of a Wise webhook payload.

Functions

create(config, attrs)

@spec create(Wise.Config.t(), map()) :: {:ok, map()} | {:error, Wise.Error.t()}

Creates a webhook subscription.

delete(config, profile_id, sub_id)

@spec delete(
  Wise.Config.t(),
  Wise.Types.profile_id(),
  Wise.Types.webhook_subscription_id()
) ::
  {:ok, :ok} | {:error, Wise.Error.t()}

Deletes a webhook subscription.

get(config, profile_id, sub_id)

@spec get(
  Wise.Config.t(),
  Wise.Types.profile_id(),
  Wise.Types.webhook_subscription_id()
) ::
  {:ok, map()} | {:error, Wise.Error.t()}

Fetches a webhook subscription by ID.

list(config, profile_id)

@spec list(Wise.Config.t(), Wise.Types.profile_id()) ::
  {:ok, list()} | {:error, Wise.Error.t()}

Lists all webhook subscriptions for a profile.

parse_event(body)

@spec parse_event(binary()) :: {:ok, map()} | {:error, term()}

Parses a raw JSON webhook body into a map. Returns {:ok, event_map} or {:error, reason}.

test(config, sub_id)

@spec test(Wise.Config.t(), Wise.Types.webhook_subscription_id()) ::
  {:ok, :ok} | {:error, Wise.Error.t()}

Triggers a test delivery for a subscription.

verify_and_parse(body, signature_header, secret)

@spec verify_and_parse(binary(), String.t(), String.t()) ::
  {:ok, map()} | {:error, Wise.Error.t() | term()}

Verifies and parses a webhook payload in one call. Returns {:ok, event_map} or {:error, Error.t()}.

verify_signature(body, signature_header, secret)

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

@spec verify_signature(term(), term(), term()) :: :ok | {:error, Wise.Error.t()}

Verifies the HMAC-SHA256 signature of a Wise webhook payload.

Uses Erlang's :crypto module — no external dependencies. Returns :ok on success or {:error, %Wise.Error{type: :invalid_signature}}.

The signature_header value may optionally be prefixed with "sha256=".