ClearBank.Webhook (ClearBank v1.0.0)

Copy Markdown View Source

Webhook envelope struct and parsing.

Every ClearBank webhook payload has the following shape:

%{
  "Type" => "TransactionSettled",
  "Version" => 1,
  "Payload" => %{ ... },
  "Nonce" => 123456789
}

The DigitalSignature and Nonce are in the HTTP headers/body.

Signature verification

Before processing any webhook, always verify the DigitalSignature header using ClearBank's public key. See ClearBank.Webhook.Verifier.

Webhook delivery guarantees

ClearBank provides at-least-once delivery. Your handler must be idempotent. Detect duplicates by comparing type, timestamp, and id in the payload. Respond within 5 seconds with a 200 containing {"nonce": <value>} and a valid DigitalSignature.

Summary

Types

t()

Functions

ack_body(webhook)

Builds the JSON response body for a webhook acknowledgement.

parse(arg1)

Parses a raw webhook body map into a %ClearBank.Webhook{} struct.

Types

t()

@type t() :: %ClearBank.Webhook{
  nonce: integer(),
  payload: map(),
  type: String.t(),
  version: non_neg_integer()
}

Functions

ack_body(webhook)

@spec ack_body(t()) :: map()

Builds the JSON response body for a webhook acknowledgement.

Returns a map %{"nonce" => nonce} ready to be JSON-encoded and returned in your HTTP response.

Examples

response_body = ClearBank.Webhook.ack_body(webhook)
# => %{"nonce" => 123456789}

parse(arg1)

@spec parse(map()) :: {:ok, t()} | {:error, :invalid_webhook}

Parses a raw webhook body map into a %ClearBank.Webhook{} struct.

Examples

raw = Jason.decode!(conn.body)
{:ok, webhook} = ClearBank.Webhook.parse(raw)