Stateless webhook signature verification with caller-pinned keys and algorithms.
Byte-key HMAC, RSA, ECDSA and Ed25519 verification returns :ok, {:error, :invalid_signature}
or {:error, :no_webhook_secret}; jws/3 and check_timestamp/3 can also return
{:error, :stale_timestamp}. jws/3 returns the authenticated payload bytes. Malformed input never raises.
encoding: describes the received signature: :hex is lowercase only,
:hex_upper uppercase only, :hex_any accepts either case, :base64 and
:base64url accept padded or unpadded strings, and :raw accepts bytes.
Keys may be a single key or a rotation list; empty keys cannot verify.
HMAC accepts AshHooks.Custody.Key values, including rotation lists mixed
with byte keys. It decodes signatures before custody verification and returns
classified custody errors. A successful rotation key authenticates the request;
otherwise configuration and availability errors take precedence over a MAC
mismatch. Byte-only failures keep their existing atom results.
HMAC evaluates every key. Byte-key comparisons use a length guard
and constant-time comparison; custodians must provide the equivalent
full-MAC comparison guarantee for opaque keys.
Asymmetric keys may be decoded :public_key terms or a PEM containing exactly
one PUBLIC KEY, RSA PUBLIC KEY, or CERTIFICATE. A certificate is only a public
key container pinned by the host: chain, expiry, and revocation are not checked.
Ed25519 also accepts a raw 32-byte public key. Key types must match the algorithm.
Asymmetric verification never goes through custody: an AshHooks.Custody.Key
in an RSA, ECDSA or Ed25519 key list returns
AshHooks.Errors.Invalid.KeyKindMismatch unless another key verifies, ranked
as HMAC ranks a rotation list.
AshHooks.Custody.PublicKey pins an asymmetric algorithm, including its
digest, padding and curve. HMAC refuses pinned public keys with
KeyKindMismatch. Asymmetric verifiers preserve that classification when
the pinned kind does not match their algorithm.
Keys are never fetched from request headers, tokens, or URLs.
Summary
Functions
Checks nonnegative Unix seconds (integer or ASCII digit string) within a symmetric positive tolerance.
Compares binary values in constant time after checking equal lengths.
Verifies ECDSA on P-256 or P-384; options: digest: (:sha256 default,
:sha384, :sha512), format: (:der default or fixed-width :raw r || s),
and encoding: (:base64 default). Other curves and incorrect widths fail.
Verifies Ed25519 with encoding: (default :base64).
Looks up a request header case-insensitively in ctx.headers, a map or an
ordered {name, value} list such as conn.req_headers. Repeated lines in a
list are joined with ", ". Returns nil when the header is absent.
Verifies HMAC; options: digest: (default :sha256, also :sha1, :sha384, :sha512) and encoding: (default :hex).
Verifies compact JWS and returns {:ok, payload_bytes}.
Verifies RSA; options: digest: (:sha256 default, :sha384, :sha512),
padding: (:pkcs1_v1_5 default or :pss) and encoding: (:base64 default).
PSS pins MGF1 to the digest and salt length to its byte length (RFC 7518).
Types
@type error() :: {:error, :invalid_signature | :no_webhook_secret | :stale_timestamp | :malformed_payload | struct()}
Functions
@spec check_timestamp(term(), map(), pos_integer()) :: :ok | {:error, :invalid_signature | :stale_timestamp}
Checks nonnegative Unix seconds (integer or ASCII digit string) within a symmetric positive tolerance.
Compares binary values in constant time after checking equal lengths.
Verifies ECDSA on P-256 or P-384; options: digest: (:sha256 default,
:sha384, :sha512), format: (:der default or fixed-width :raw r || s),
and encoding: (:base64 default). Other curves and incorrect widths fail.
Verifies Ed25519 with encoding: (default :base64).
Looks up a request header case-insensitively in ctx.headers, a map or an
ordered {name, value} list such as conn.req_headers. Repeated lines in a
list are joined with ", ". Returns nil when the header is absent.
Verifies HMAC; options: digest: (default :sha256, also :sha1, :sha384, :sha512) and encoding: (default :hex).
Verifies compact JWS and returns {:ok, payload_bytes}.
alg: is required and must exactly match the protected header: HS256/384/512,
RS256/384/512, PS256/384/512, ES256, ES384, or EdDSA. ES algorithms pin the
curve and raw signature format. none, nonempty crit, and b64: false fail,
as do padded segments (RFC 7515 encodes them without =).
Key-location headers are ignored. JSON object exp and nbf claims must be
numeric and are checked only after verification, against now_ms: or the clock.
json_decoder: accepts a one-argument decoder for both the protected header
and claims, defaulting to Jason.decode/1. A header it refuses is
{:error, :invalid_signature}; a payload it does not decode to a JSON object
is not claim-checked; invalid claim types remain {:error, :invalid_signature}.
The authenticated payload is returned as bytes, so the caller's own decode
decides whether it is acceptable.
Verifies RSA; options: digest: (:sha256 default, :sha384, :sha512),
padding: (:pkcs1_v1_5 default or :pss) and encoding: (:base64 default).
PSS pins MGF1 to the digest and salt length to its byte length (RFC 7518).