The legacy HMAC webhook envelope for receivers using the :legacy or
:dual signing modes.
AshHooks.Legacy.verify/5 validates its signature.
Envelope:
- MAC: HMAC-SHA256 over
"<unix_ts>.<body>", lowercase hex. sign/3→"v1=<hex>"; rotation appends",v1prev=<hex>"under the separately imported previous secret.- header:
x-webhook-signature: t=<unix_ts>,<signature>.
headers/4 also accepts AshHooks.Custody.Key values of kind
{:legacy_hmac, :sha256} for either slot, including mixed byte and custody
rotation. Failures return classified errors; sender-only kinds are refused
before custody is called. Byte clauses retain their existing behavior.
Use :dual to send this envelope alongside Standard Webhooks while receivers
migrate. New integrations should use :standard.
Summary
Functions
Assembles the header value: t=<unix_ts>,<signature>.
The legacy header set: x-webhook-signature under secret (and optional previous).
HMAC-SHA256 over <unix_ts>.<body>, lowercase hex, v1=-prefixed.
Current and previous signatures comma-joined (zero-downtime rotation).
Verifies a legacy header value: parses t=/v1=, compares hex digests
in constant time, then checks the replay window. An invalid signature takes
precedence over a stale timestamp.
Functions
Assembles the header value: t=<unix_ts>,<signature>.
@spec headers( binary() | AshHooks.Custody.Key.t(), binary() | AshHooks.Custody.Key.t() | nil, binary(), integer() ) :: %{required(String.t()) => String.t()} | {:error, struct() | :kind_not_allowed}
The legacy header set: x-webhook-signature under secret (and optional previous).
HMAC-SHA256 over <unix_ts>.<body>, lowercase hex, v1=-prefixed.
Current and previous signatures comma-joined (zero-downtime rotation).
@spec verify(binary(), binary(), binary(), integer(), integer()) :: {:ok, %{unix_ts: integer()}} | {:error, :invalid_signature | :stale_timestamp}
Verifies a legacy header value: parses t=/v1=, compares hex digests
in constant time, then checks the replay window. An invalid signature takes
precedence over a stale timestamp.
window defaults to 300 seconds, symmetric around now_ts.