A caller-configured webhook verification contract.
The Verify any sender guide has recipes for common signature shapes.
Define a provider with use AshHooks.Provider, verify: [...] or validate trusted
options with new!/1 and call verify/4. Request data never chooses algorithms,
keys, encodings, or canonicalization callbacks.
Required options are algorithm: and signature:. Algorithms are
:hmac_sha1, :hmac_sha256, :hmac_sha384, :hmac_sha512,
:rsa_pkcs1_sha256, :rsa_pkcs1_sha384, :rsa_pkcs1_sha512,
:rsa_pss_sha256, :rsa_pss_sha384, :rsa_pss_sha512,
:ecdsa_p256_sha256, :ecdsa_p384_sha384, and :ed25519.
ECDSA algorithms pin the curve as well as the digest.
signature: accepts {:header, name}, {:header, name, prefix: prefix},
{:structured_header, name, signature_key: key}, or :jws_body. A header prefix
matches ASCII case-insensitively. Structured headers support pair_separator:
(default ",") and key_value_separator: (default "="), consider at most 16
matching signatures, and accept any matching signature.
HMAC schemes accept opaque AshHooks.Custody.Key values and rotation lists
mixing custody and byte keys. Key encodings and prefixes apply only to byte
keys; signature encodings are decoded before custody verification. Custody
failures remain classified. Public-key algorithms use pinned public keys
outside custody.
Other options:
encoding::hex,:hex_upper,:hex_any,:base64, or:base64url; default:hexfor HMAC,:base64for public keys.ecdsa_format::der(default) or:raw, only for ECDSA.key_encoding::raw(default),:hex,:base64, or:base64urlfor HMAC secrets and raw Ed25519 keys. PEM is detected automatically.key_prefix: optional literal prefix removed before key decoding when present.signed_input::body(default), a nonempty list of binary literals,:body,:timestamp,:method,:url,:path,{:header, name}, or{:base64, part}, concatenated without separators. Alternatively a{module, function}or two-argument function(raw_body, ctx) -> binary.:pathpreserves encoding and excludes the query;:urlpreserves the URI.timestamp:nil(default),{:header, name},{:signature_field, key}for structured signatures, or a{module, function}/ two-argument function returning{:ok, unix_seconds}or:error.timestamp_unit::seconds(default) or:millisecondsfor header/field timestamps. Milliseconds use integer division by 1000.tolerance_seconds: positive integer, default 300; overridden byctx[:replay_window_seconds]. The clock isctx[:now_ms]or system time.
A configured JWS-body provider deduplicates on payload_identity/1 unless the
inbound declaration sets an event_id extractor or the provider overrides
event_identity/1.
JWS bodies derive the pinned JWS algorithm from algorithm:. They reject
HMAC-SHA1 and any encoding:, ecdsa_format:, signed_input: or
timestamp_unit:. A timestamp: must be a host function, and
tolerance_seconds: requires one. JSON object
exp/nbf claims are also enforced by AshHooks.Provider.Signature.jws/3.
Keys are decoded first, then signatures extracted and input built. Timestamp checks run only after successful authentication. Certificates are pinned key containers only; no chain, expiration, or revocation validation is performed.
Summary
Functions
Decodes a JWS body's payload to a map or list through the supplied JSON
decoder, defaulting to Jason.decode/1. This helper does not authenticate it.
Validates trusted options and returns a normalized scheme; invalid configuration raises ArgumentError.
The default deduplication identity of a configured JWS-body provider: the lowercase hex SHA-256 of the verified payload as canonical JSON (object keys sorted). Two encodings of the same signed content, such as an ECDSA signature and its equally valid negated form, therefore share one ledger identity.
Returns :body for JWS envelopes and :request for header-based signatures.
Returns the configured timestamp header, or nil for absent and host-function timestamps.
Verifies exact request bytes using a validated scheme or trusted keyword options.
Types
Functions
@spec decode_payload(binary(), t(), (binary() -> {:ok, term()} | {:error, term()})) :: {:ok, map() | list()} | {:error, :malformed_payload}
Decodes a JWS body's payload to a map or list through the supplied JSON
decoder, defaulting to Jason.decode/1. This helper does not authenticate it.
Validates trusted options and returns a normalized scheme; invalid configuration raises ArgumentError.
The default deduplication identity of a configured JWS-body provider: the lowercase hex SHA-256 of the verified payload as canonical JSON (object keys sorted). Two encodings of the same signed content, such as an ECDSA signature and its equally valid negated form, therefore share one ledger identity.
@spec signature_source(t()) :: :body | :request
Returns :body for JWS envelopes and :request for header-based signatures.
Returns the configured timestamp header, or nil for absent and host-function timestamps.
Verifies exact request bytes using a validated scheme or trusted keyword options.
Keyword options are validated first: an invalid configuration raises
ArgumentError, as new!/1 does. Request data never raises; it returns an error.