Standard Webhooks signing and verification for v1 (HMAC-SHA256) and
v1a (ed25519), over msg_id.timestamp.payload.
Pass the exact payload bytes. headers/4 assembles the webhook ID,
timestamp, and signatures; verify/4 validates those headers against the
received bytes and enforces a timestamp tolerance by default.
Secret formats:
- symmetric:
whsec_+ base64 of 24 to 64 random bytes (prefix optional, matching the references).sign/4enforces the 24 to 64 byte band (the emitter's length bound); verification accepts nonempty decoded symmetric secrets, including shorter keys, and rejects malformed base64. - asymmetric:
whsk_+ base64 of the 32-byte ed25519 seed (signing),whpk_+ base64 of the 32-byte public key (verification). Prefixes are required; they are whatverify/4dispatches on.
headers_for_mode/5 emits :standard, :dual (Standard Webhooks and
legacy), or :legacy headers for the delivery runtime. Rotation options
include the previous key's signature alongside the current signature.
Signing and header builders also accept AshHooks.Custody.Key values.
Their kind selects v1 or v1a independently for each slot. Custody failures
return {:error, classified_error}; sender-only kinds return
{:error, :kind_not_allowed} before custody is called. Byte clauses retain
their existing values and exceptions.
Summary
Functions
Displays a spec key's fingerprint as SHA256: plus unpadded base64url.
A fresh msg_-prefixed webhook id (URL-safe, never contains .).
A fresh whsec_-prefixed secret (24 to 64 decoded bytes, spec band).
A fresh ed25519 keypair as {whsk, whpk}.
The three Standard Webhooks headers. :whsec and/or :whsk select the
signature schemes; :previous_whsec / :previous_whsk
append the rotated-out key's signature (space-delimited, per the spec's
zero-downtime rotation, symmetric and asymmetric alike).
The headers produced for each signing mode
Signs the canonical string with HMAC-SHA256 under a decoded byte secret,
returning "v1," <> base64(mac). A custody key selects v1 HMAC or v1a
Ed25519 from its kind and returns the corresponding signature string.
Custody failures return classified package errors; sender-only kinds return
{:error, :kind_not_allowed}.
Signs the canonical string with ed25519 under the seed decoded from a
whsk_ byte secret, returning "v1a," <> base64(signature). Invalid byte
inputs raise ArgumentError. Custody keys delegate to sign/4: their kind
selects v1 or v1a, and failures return its classified errors or
{:error, :kind_not_allowed}.
Verifies a webhook's webhook-id / webhook-timestamp /
webhook-signature headers against the raw payload.
Types
Functions
Displays a spec key's fingerprint as SHA256: plus unpadded base64url.
The digest is the first 16 bytes of
SHA-256("ash_hooks key fingerprint v1\0" <> kind_label <> "\0" <> key_bytes).
whsec_ uses the label standard_webhooks.v1 and its 24 to 64 decoded
HMAC bytes. whsk_ and whpk_ use standard_webhooks.v1a and the Ed25519
public key, deriving it first for a 32-byte seed. Both halves of a pair
therefore display the same fingerprint. Other inputs return
{:error, :not_a_spec_key}.
Safe to show for securely generated keys. This truncated, domain-separated
hash does not protect weak or predictable secrets from offline guessing.
It is distinct from AshHooks.Telemetry.fingerprint/1, which is for
correlation only. Opaque custody keys use AshHooks.Custody.display_fingerprint/1.
@spec generate_msg_id() :: String.t()
A fresh msg_-prefixed webhook id (URL-safe, never contains .).
@spec generate_secret(pos_integer()) :: String.t()
A fresh whsec_-prefixed secret (24 to 64 decoded bytes, spec band).
A fresh ed25519 keypair as {whsk, whpk}.
@spec headers(String.t(), integer(), binary(), keyword() | AshHooks.Custody.Key.t()) :: %{required(String.t()) => String.t()} | {:error, struct() | :kind_not_allowed}
The three Standard Webhooks headers. :whsec and/or :whsk select the
signature schemes; :previous_whsec / :previous_whsk
append the rotated-out key's signature (space-delimited, per the spec's
zero-downtime rotation, symmetric and asymmetric alike).
@spec headers_for_mode( :legacy | :dual | :standard, String.t(), integer(), binary(), keyword() ) :: %{required(String.t()) => String.t()} | {:error, struct() | :kind_not_allowed}
The headers produced for each signing mode:
:standard: the three SW headers.:dual: SW headers PLUS the byte-identical legacy envelope (x-webhook-signature, viaAshHooks.Legacy); requires:legacy_secret(dual MEANS both envelopes).:legacy: the legacy envelope only.
Legacy options: :legacy_secret, :legacy_previous_secret. SW options:
:whsec, :whsk, :previous_whsec, and :previous_whsk.
@spec sign(String.t(), integer(), binary(), String.t() | AshHooks.Custody.Key.t()) :: String.t() | {:error, struct() | :kind_not_allowed}
Signs the canonical string with HMAC-SHA256 under a decoded byte secret,
returning "v1," <> base64(mac). A custody key selects v1 HMAC or v1a
Ed25519 from its kind and returns the corresponding signature string.
Custody failures return classified package errors; sender-only kinds return
{:error, :kind_not_allowed}.
Raises ArgumentError on invalid inputs; the send path fails loud on
config or programming errors.
@spec sign_ed25519( String.t(), integer(), binary(), String.t() | AshHooks.Custody.Key.t() ) :: String.t() | {:error, struct() | :kind_not_allowed}
Signs the canonical string with ed25519 under the seed decoded from a
whsk_ byte secret, returning "v1a," <> base64(signature). Invalid byte
inputs raise ArgumentError. Custody keys delegate to sign/4: their kind
selects v1 or v1a, and failures return its classified errors or
{:error, :kind_not_allowed}.
@spec verify(binary(), map(), String.t(), keyword()) :: {:ok, %{id: String.t(), timestamp: integer()}} | {:error, verify_reason()}
Verifies a webhook's webhook-id / webhook-timestamp /
webhook-signature headers against the raw payload.
Dispatches on the secret's prefix: whpk_ verifies v1a (ed25519)
entries; anything else verifies v1 (HMAC) entries and skips all other
version identifiers.
headers is a map with lowercased header names as string keys
and single binary values ("webhook-id", "webhook-timestamp",
"webhook-signature"), the shape Plug and the inbound seam supply after
normalization. Mixed-case keys or multi-value header lists are
{:error, :missing_header} (fail closed); callers normalize before this
boundary.
Options:
:now: integer unix seconds (defaultSystem.system_time(:second)).:tolerance: allowed|now - timestamp|in seconds (default 300).:ignore_timestamp: skip the tolerance check (dead-letter re-drives, offline verification); the timestamp must still parse.
Signature verification precedes the timestamp window check in both schemes.
A bad signature returns :invalid_signature even when the timestamp is stale.
Returns {:ok, %{id: id, timestamp: ts}} or {:error, reason}. Never
raises on hostile input.