# webhook-verify — Technical Specification
Status: draft v0.1
Audience: contributors and implementers (human or AI agent)
This document defines the contract the crate must satisfy: the public API,
the per-provider signing schemes, error semantics, security requirements,
and the testing bar every provider implementation must clear before merge.
---
## 1. Goals and non-goals
**Goals**
- Verify that an inbound HTTP request genuinely originated from a given
webhook provider and was not tampered with in transit.
- Provide one consistent API across all supported providers.
- Be correct by construction: every provider backed by vendor-sourced test
vectors, constant-time comparison, and (where applicable) replay
protection.
- Be embeddable: no required async runtime, no required web framework, no
network calls, `no_std + alloc` compatible for the core verification path
where the underlying crypto crates allow it.
**Non-goals**
- Parsing/deserializing the webhook event payload into typed structs.
- Registering, sending, or replaying webhooks.
- Idempotency / deduplication of events (a signature-verified request can
still be a legitimate retry — that's a separate concern).
- Acting as a proxy, gateway, or hosted service.
---
## 2. Core API
```rust
pub enum Provider {
Stripe,
GitHub,
Shopify,
Slack,
Square,
Twilio,
Discord,
PayPal,
SendGrid,
Linear,
Zoom,
Dropbox,
StandardWebhooks,
Custom(CustomScheme),
}
pub struct Secret(/* redacted */);
impl Secret {
pub fn new(value: impl Into<String>) -> Self;
}
// Debug/Display for Secret print "Secret(**redacted**)" only.
/// Caller-supplied asymmetric verification material (spec §7).
#[non_exhaustive]
pub enum VerifyingKeyMaterial {
X509Certificate(Vec<u8>), // PayPal (shipped, feature `paypal`)
EcdsaP256PublicKey(Vec<u8>), // SendGrid (shipped, feature `sendgrid`)
}
// Debug redacts the key/certificate bytes (variant name + byte length only).
pub struct VerifyOptions { // #[non_exhaustive]: configure via Default + the
// `with_*` builders so new fields stay non-breaking
/// Maximum allowed age between the signed timestamp and "now",
/// for providers whose scheme includes a timestamp. `None` disables
/// the check (not recommended). Default: Some(Duration::from_secs(300)).
pub max_age: Option<Duration>,
/// Clock used for "now", injectable for deterministic tests.
pub clock: Option<Arc<dyn Clock>>,
/// Full URL of the receiving endpoint, for URL-scoped schemes
/// (currently Square, Twilio). See §3.
pub request_url: Option<String>,
/// Parsed `application/x-www-form-urlencoded` fields, required by
/// schemes that sign form fields rather than the raw body
/// (currently Twilio). Pass every field as received; sorting into
/// signing order happens here. See §3.
pub form_params: Option<Vec<(String, String)>>,
/// Asymmetric public-key/certificate material for schemes that verify
/// against a configured key rather than a shared secret (currently
/// SendGrid's ECDSA P-256 key, PayPal's X.509 certificate).
/// Required-but-absent fails closed with `MissingContext`; malformed
/// material with `InvalidSecret`. This crate never fetches key material
/// (§7). See §3.
pub verifying_material: Option<VerifyingKeyMaterial>,
/// Merchant/webhook-subscription ID required by PayPal's signed-string
/// construction (`{transmission_id}|{transmission_time}|{webhook_id}|
/// {crc32}`). The webhook ID does not travel in the request — it is the
/// subscription ID configured in the PayPal Developer Portal — so the
/// caller supplies it here. Required-but-absent for `Provider::PayPal`
/// fails closed with `MissingContext`. No effect on other providers.
pub webhook_id: Option<String>,
}
impl Default for VerifyOptions {
fn default() -> Self {
Self {
max_age: Some(Duration::from_secs(300)),
clock: None,
request_url: None,
form_params: None,
verifying_material: None,
webhook_id: None,
}
}
}
pub trait HeaderMap {
/// Case-insensitive header lookup. Returns the first matching value.
fn get(&self, name: &str) -> Option<&str>;
}
// Blanket impls provided for the built-in collections (Vec<(String,String)>,
// Vec<(&str,&str)>, fixed-size arrays of (String,String) and (&str,&str),
// borrowed slices of both, BTreeMap<String,String>, HashMap<String,String>),
// unconditionally; the http::HeaderMap impl is provided behind the "http"
// feature flag.
pub fn verify(
provider: Provider,
headers: &dyn HeaderMap,
raw_body: &[u8],
secret: &Secret,
options: VerifyOptions,
) -> Result<(), VerifyError>;
```
Implementation status (kept in sync with the code — do not let this drift):
- All `Provider` variants ship up front so adding providers later is
non-breaking. A variant whose implementation is disabled by a crate
feature flag fails closed: `verify()` returns `UnsupportedProvider` for it
(currently PayPal/SendGrid without their features).
- `Custom(CustomScheme)` ships per §2.2: declarative hash/encoding/prefix/
header configuration plus a caller-supplied signed-string function, with
the same constant-time comparison and fail-closed parsing guarantees as
built-in providers. When `timestamp_header` is set, replay protection
applies with the shared symmetric tolerance semantics (`|now - t| <=
max_age`) used by the built-in timestamped schemes; when it is `None`,
no clock is consulted (mirroring GitHub/Linear).
### 2.1 `VerifyError`
```rust
#[non_exhaustive]
pub enum VerifyError {
MissingHeader { header: &'static str },
MalformedHeader { header: &'static str, reason: &'static str },
BadEncoding { reason: &'static str },
SignatureMismatch,
TimestampOutOfTolerance { skew: Duration, max_age: Duration },
UnsupportedProvider,
InvalidSecret { reason: &'static str },
MissingContext { reason: &'static str },
}
```
Design rules for errors:
- `VerifyError` **never** includes the secret, the raw body, or the computed
signature in its `Display` output. It may include header *names* and
numeric skew values.
- `SignatureMismatch` must be returned in exactly the same way regardless of
*how close* the provided signature was to correct (no early-return that
could leak timing information about which byte differed).
- Distinguish `MissingHeader` / `MalformedHeader` from `SignatureMismatch`
in the type system (useful for callers who want to log malformed-request
noise differently from active-attack signals), but treat both as "reject
the request" outcomes — never treat a malformed header as "skip
verification."
- `MissingContext` signals caller misconfiguration (required request context,
such as Square's notification URL, absent from `VerifyOptions`) rather than
malformed or forged input. It exists so configuration errors are not
disguised as `SignatureMismatch` attack signals; the request is still
rejected.
#### `verify_any` aggregation (decision record, issue #64)
`verify_any()` iterates a slice of secrets during a rotation window and
returns `Ok(())` if any one of them verifies. Its error aggregation rules:
- **Structural errors** (`MissingHeader`, `MalformedHeader`, `BadEncoding`,
`UnsupportedProvider`, `MissingContext`, `TimestampOutOfTolerance`) are
deterministic across all secrets — they occur before any secret-dependent
work — so `verify_any` returns them immediately.
- **`InvalidSecret` is secret-specific, not deterministic.** A key rejected
for its own formatting is unusable for the current request, but a later key
in the slice may still be correct. `verify_any` therefore *continues*
past an `InvalidSecret` rather than aborting, so a rotation slice with one
garbled/truncated live key still verifies against the healthy one.
- On total failure, `verify_any` returns `SignatureMismatch` if at least one
key was well-formed but wrong; it returns the first `InvalidSecret` only
when *every* key was rejected for its own formatting (an all-garbled
configuration is an operator error, not a forgery). Returning
`InvalidSecret` in that case cannot help an attacker — a forged request
already yields `SignatureMismatch` whenever a usable key exists — and it
gives operators an honest signal that their key configuration is broken.
### 2.2 `CustomScheme`
For providers not yet built in, or self-hosted/internal webhook senders:
```rust
pub struct CustomScheme {
pub hash: HashAlg, // Sha256 | Sha1 | Sha512
pub signature_header: &'static str,
pub timestamp_header: Option<&'static str>,
pub encoding: Encoding, // Hex | Base64
pub prefix: Option<&'static str>, // e.g. "sha256=" or "v0="
pub signed_string: fn(&dyn HeaderMap, &[u8]) -> Vec<u8>,
}
```
This lets callers cover a long-tail provider today without waiting on a
crate release, and it's how new built-in providers get prototyped before
being promoted into the `Provider` enum.
---
## 3. Per-provider signing schemes
Each entry below is the normative definition an implementation must match.
Every row must ship with at least one test vector taken from the provider's
own published documentation (linked in code comments) plus at least one
locally-constructed vector covering a boundary case (empty body, unicode
body, multi-value headers, etc.).
### Stripe
- Header: `Stripe-Signature: t=<unix_ts>,v1=<hex_hmac>[,v0=<legacy>]`
- Signed string: `"{t}.{raw_body}"` (literal dot join, UTF-8 bytes)
- Algorithm: HMAC-SHA256, hex-encoded
- Replay protection: compare `t` against `max_age` (Stripe's own SDKs
default to 5 minutes)
- Multiple `v1=` values may be present during secret rotation; a match on
*any* is accepted.
- Timestamp validation: `t` must be a pure ASCII-digit unix-seconds value,
validated through the shared timestamp parser. Sign-prefixed
(`t=+1700000000`), whitespace-padded, empty, or overflowing values are
rejected as `MalformedHeader` — the same fail-closed policy every other
timestamped provider applies (`spec.md` §4.4), regardless of whether a
signature over the non-canonical string would verify.
### GitHub
- Header: `X-Hub-Signature-256: sha256=<hex_hmac>`
- Signed string: raw body bytes, unmodified
- Algorithm: HMAC-SHA256, hex-encoded
- No built-in timestamp; GitHub does not include replay protection at the
signature layer. `max_age` has no effect for this provider — document
this explicitly rather than silently ignoring the option.
- Legacy `X-Hub-Signature` (SHA1) supported only via `CustomScheme` — not a
default path, since GitHub itself deprecated SHA1.
### Shopify
Source: <https://shopify.dev/docs/apps/build/webhooks/subscribe/https>
(Shopify's HTTPS webhook subscription and verification documentation).
- Header: `X-Shopify-Hmac-Sha256: <base64_hmac>` (lookup is case-insensitive;
this matches the casing in Shopify's own docs)
- Signed string: raw body bytes, unmodified
- Algorithm: HMAC-SHA256, **base64**-encoded (not hex — a common bug source)
- No timestamp in the signature scheme.
- Test-vector provenance: Shopify's docs describe the scheme but publish no
concrete test vector, so the implementation is validated against locally
constructed, deterministic vectors over the documented recipe (base64 of
the exact construction above). Replace them if Shopify ever publishes
fixed vectors.
### Dropbox
Source: <https://www.dropbox.com/developers/reference/webhooks> ("Webhooks"
documentation, signature verification guidance and Python example code).
- Header: `X-Dropbox-Signature: <hex_hmac>`
- Signed string: raw body bytes, unmodified
- Algorithm: HMAC-SHA256, hex-encoded
- No timestamp in the signature scheme (`max_age` has no effect).
- Test-vector provenance: Dropbox's docs and Python example code describe the
construction but publish no byte-exact example signature, so the
implementation is validated against locally constructed, deterministic
vectors over exactly the documented construction. Replace them if Dropbox
ever publishes fixed vectors.
### Linear
Source: <https://developers.linear.app/docs/graphql/working-with-the-graphql-api/webhooks>
(Linear's webhook signature verification documentation).
- Header: `linear-signature: <hex_hmac>`
- Signed string: raw body bytes, unmodified
- Algorithm: HMAC-SHA256, hex-encoded
- No timestamp in the signature scheme.
- Test-vector provenance: Linear's docs describe the construction but publish
no byte-exact example signature, so the implementation is validated against
locally constructed, deterministic vectors over exactly the documented
construction. Replace them if Linear ever publishes fixed vectors.
### Slack
- Headers: `X-Slack-Signature: v0=<hex_hmac>`, `X-Slack-Request-Timestamp`
- Signed string: `"v0:{timestamp}:{raw_body}"`
- Algorithm: HMAC-SHA256, hex-encoded
- Replay protection required: Slack explicitly recommends rejecting
requests where `|now - timestamp| > 300s`.
### Square
Source: <https://developer.squareup.com/docs/webhooks/step3validate> ("Verify
and Validate an Event Notification") and the reference implementations in
Square's official SDKs (e.g. `square-python-sdk`
`square/utils/webhooks_helper.py`, `square-php-sdk` `WebhooksHelper`).
- Header: `x-square-hmacsha256-signature: <base64_hmac>`
- Signed string: `"{notification_url}{raw_body}"` — the webhook subscription's
notification URL concatenated directly with the raw body, no separator.
Verification cannot proceed from headers + body + secret alone, so the
caller supplies the URL via
[`VerifyOptions::request_url`] (decided API shape; a missing or empty URL
fails closed with `MissingContext`). The value must be the exact
dashboard-configured constant — reconstructing it from request headers
behind a proxy is the classic failure mode.
- Secret is the subscription's signature key used **as its UTF-8 bytes**.
Provenance note: earlier drafts of this spec said the key arrives
hex-encoded and must be decoded first. That matched Square's retired key
format but not any current official source: every current SDK hashes the key
string as UTF-8 directly, and the docs' own example key (`asdf1234`) is not
valid hexadecimal. An empty key fails closed with `InvalidSecret`.
- Algorithm: HMAC-SHA256 over the signed string, base64-encoded
- No timestamp in the signature scheme (`max_age` has no effect).
### Twilio
Source: <https://www.twilio.com/docs/usage/security#validating-requests>
("Validating requests are coming from Twilio", including the docs' own
worked example) and the reference implementations in Twilio's official SDKs
(e.g. `twilio-python`'s `twilio/request_validator.py`).
- Header: `X-Twilio-Signature: <base64_hmac_sha1>`
- Signed string: the full request URL (protocol through query string,
exactly as configured with Twilio), followed by the `POST` form fields
sorted alphabetically by name in Unix-style byte order, each field's name
and value concatenated directly to the string with no delimiter.
- Algorithm: HMAC-SHA1, base64-encoded. HMAC construction is not affected by
SHA-1's collision attacks given a secret key, which is why the scheme
remains SHA-1.
- Key: the account's Auth Token as its UTF-8 bytes; an empty token fails
closed with `InvalidSecret`.
- Not a raw-body scheme: the signature covers the parsed form fields, not
the body bytes. Callers pass every received field via
[`VerifyOptions::form_params`] (decided API shape; the URL goes in
`VerifyOptions::request_url`). Sorting is applied by this crate — callers
pass fields in any order. A duplicate field name keeps its received
relative order (the official SDKs use keyed dicts, which cannot represent
duplicates). Omitting either option fails closed with `MissingContext`.
An explicitly empty parameter list is meaningful (the JSON-body variant
carries a `bodySHA256` query parameter and signs the URL alone).
- No timestamp in the signature scheme (`max_age` has no effect).
### Discord
Source: <https://docs.discord.com/developers/interactions/overview>
("Validating Security Request Headers") and the reference implementations in
Discord's official SDKs (`discord-interactions-js`,
`discord-interactions-python`).
- Headers: `X-Signature-Ed25519`, `X-Signature-Timestamp`
- Signed message: `"{timestamp}{raw_body}"` — the timestamp verbatim from
its header, immediately followed by the raw body bytes
- Algorithm: Ed25519 signature verification against Discord's provided
**public key** (not a shared secret — `Secret` here holds the hex-encoded
public key, not an HMAC key; document this distinction prominently since
it changes the security model). Malformed keys (non-hex, wrong length)
fail closed with `InvalidSecret`.
- Replay protection: enforced with the shared default tolerance
(symmetric `|now - t| <= max_age`). Discord's docs define no recommended
window; the timestamp exists so receivers *can* reject stale deliveries,
and spec §5.4 requires a tolerance for timestamped schemes. Callers can
widen or disable via `max_age`.
- Test vectors: Discord publishes no frozen vectors today (their SDK tests
generate ephemeral keypairs; the docs show placeholder keys). The
implementation is validated against locally constructed, deterministic
vectors over exactly the officially documented construction. Replace them
if Discord ever publishes fixed vectors.
### PayPal
Source: PayPal's official "Self verification method" documentation
(<https://developer.paypal.com/api/rest/webhooks/rest/#message-verification>)
and the sample postback code in that same doc page. The crate never performs
a postback or any network I/O (see the resolved design question in §7): the
certificate is supplied by the caller, mirroring SendGrid (§3).
- Headers: `PayPal-Transmission-Id`, `PayPal-Transmission-Time` (RFC 3339
instant, e.g. `2024-05-16T05:19:23Z`), `PayPal-Transmission-Sig` (base64,
standard alphabet, padded), `PayPal-Cert-Url`, `PayPal-Auth-Algo`. All five
are required; any missing header fails closed with `MissingHeader`, and any
present-but-empty value fails closed with `MalformedHeader` ("header is
empty") rather than surfacing a guaranteed mismatch as `SignatureMismatch`.
- `PayPal-Auth-Algo` must equal `SHA256withRSA` (matched case-insensitively);
anything else fails closed with `MalformedHeader` so a future algorithm
change is rejected rather than silently mis-verified.
- Signed string: `"{transmission_id}|{transmission_time}|{webhook_id}|{crc32}"`
— the first two fields verbatim from their headers, the webhook ID from
`VerifyOptions::webhook_id` (it does not travel in the request; see below),
and the CRC-32 checksum rendered in **decimal**. The CRC-32 is the IEEE
802.3/zlib polynomial (as the official sample code computes) over the
**raw body bytes** (§4.2).
- Algorithm: RSASSA-PKCS1-v1_5 with SHA-256, i.e. Java-style
`SHA256withRSA`, over the signed string. The signature bytes are exactly
the modulus length; other lengths fail closed with `BadEncoding`.
- Key material: the X.509 certificate at `PayPal-Cert-Url`. It is a
required *header* (fail-closed on `MissingHeader` if absent) but it is
**never fetched**: the caller supplies an already vetted certificate
(typically downloaded from a personally allow-listed `PayPal-Cert-Url`) as
`VerifyingKeyMaterial::X509Certificate` (DER or PEM; only the embedded RSA
public key is used; no chain validation or hostname checking). Missing
material fails closed with `MissingContext`; unparseable certificates or
non-RSA certificates fail closed with `InvalidSecret`.
- `VerifyOptions::webhook_id` is the PayPal webhook-subscription ID shown in
the Developer Portal — required for `Provider::PayPal`; missing or empty
(`MissingContext`) fails closed. It is part of the signed string, so a
wrong non-empty ID rejects as a signature mismatch.
- The shared `Secret` argument is accepted for API uniformity and ignored
(public-key scheme, like Discord).
- Replay protection: PayPal's docs ["Compare timestamps to prevent replay
attacks"](https://developer.paypal.com/community/blog/paypal-has-updated-its-webhook-verification-endpoint/)
recommend rejecting stale `PayPal-Transmission-Time` values but define no
numeric window, so the shared default tolerance (symmetric
`|now - t| <= max_age`, 300s, injectable clock) is applied. The RFC 3339
instant is normalized to UTC (offsets and fractional seconds — truncated,
not rounded — are supported) before the window applies.
- Feature gate: shipped behind `features = ["paypal"]` (optional `rsa`,
`x509-parser`, `crc32fast`; `no_std`-compatible). Without the feature,
`Provider::PayPal` fails closed with `UnsupportedProvider`.
- Test-vector provenance: PayPal publishes no byte-exact *signed* test vector
(their example signature covers a transmission string built from a body the
docs stress must be the exact received bytes, which cannot be reconstructed
from the docs). The ci tests therefore freeze a locally generated
certificate + signature over exactly the documented construction, using
PayPal's own published example body, transmission ID, transmission time,
and webhook ID; the CRC-32 is cross-checked independently (Python
`zlib.crc32`). The private key is never committed.
### SendGrid
Source: Twilio's official "Signature Verification" documentation for the
Email Event Webhook
(<https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-signature-verification>)
and the canonical server-side implementation in `sendgrid-go`
`helpers/eventwebhook/eventwebhook.go`
(<https://github.com/sendgrid/sendgrid-go/blob/main/helpers/eventwebhook/eventwebhook.go>).
- Headers: `X-Twilio-Email-Event-Webhook-Signature` and
`X-Twilio-Email-Event-Webhook-Timestamp` (integer unix seconds)
- Signed message: `"{timestamp}{raw_body}"` — the timestamp verbatim from
its header, immediately followed by the raw request body bytes, no
separator. SHA-256 of the whole message is what ECDSA operatively
verifies (matching Go's `hash.Write(ts); hash.Write(payload)`).
- Algorithm: ECDSA over NIST P-256 (secp256r1), digest SHA-256.
- Signature encoding: base64 (standard alphabet, padded) of the ASN.1 DER
form `SEQUENCE { INTEGER r, INTEGER s }`. Non-canonical/undersized DER and
scalars ≥ the curve order fail closed with `BadEncoding` (parsed by
RustCrypto's `ecdsa` DER reader).
- Key material: the "Verification Key" from the dashboard is a base64
encoding of the ECDSA P-256 public key in `SubjectPublicKeyInfo` DER
(Go's `x509.ParsePKIXPublicKey`). Callers pass the **decoded DER bytes**
as `VerifyingKeyMaterial::EcdsaP256PublicKey`; the base64 string is **not**
accepted (documented in the provider module docs). Algorithm/certificate
OIDs in the SPKI must match `id-ecPublicKey` + `prime256v1`: a key for a
different curve/algorithm fails closed with `InvalidSecret`, not
`SignatureMismatch`.
- The shared `Secret` argument is accepted for API uniformity and ignored
(this is a public-key scheme, like Discord).
- Replay protection: enforced with the shared default tolerance (symmetric
`|now - t| <= max_age`). Twilio's docs define no numeric window; the
timestamp exists so receivers can reject stale events. Callers can widen
or disable via `max_age`.
- Feature gate: shipped behind `features = ["sendgrid"]` (optional `p256`
dependency, `no_std`-compatible). Without the feature, `Provider::SendGrid`
fails closed with `UnsupportedProvider`.
- Test vectors: the primary vector is SendGrid's own (`sendgrid-go`
`helpers/eventwebhook/eventwebhook_test.go`): key, signature, and
timestamp reproduced verbatim, body byte-identical to Go's `json.Marshal`
output plus trailing `\r\n`. Additional vectors are locally constructed
with deterministic seeds over exactly the documented construction.
### Zoom
Source: <https://developers.zoom.us/docs/api/webhooks/> ("Verify webhook
events") and Zoom's official sample app
(<https://github.com/zoom/webhook-sample-node.js>).
- Headers: `x-zm-signature: v0=<hex_hmac>`, `x-zm-request-timestamp`
- Signed string: `"v0:{timestamp}:{raw_body}"` — the version prefix, the
timestamp exactly as it appears in its header, and the raw request body
bytes, joined by literal colons. Identical construction to Slack's scheme.
- Algorithm: HMAC-SHA256, hex-encoded, prefixed `v0=` in the header
- Key: the webhook secret token as a plain UTF-8 string (not decoded).
- Replay protection: compare `|now - t|` against [`VerifyOptions::max_age`]
(default 300s), using the shared symmetric tolerance semantics. Zoom's
docs do not define a recommended window; the timestamp exists so receivers
*can* reject stale deliveries.
- Test-vector provenance: Zoom's docs and sample app publish example headers
but no byte-exact example signature, so the implementation is validated
against locally constructed, deterministic vectors over exactly the
documented construction (the vector's timestamp mirrors the docs' example
headers). Replace them if Zoom ever publishes fixed vectors.
### Standard Webhooks spec
Source: <https://www.standardwebhooks.com> and the canonical spec at
<https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md>
(reference implementations in that repo are the tie-breaker for any
ambiguity).
- Headers: `webhook-id`, `webhook-timestamp` (integer unix seconds),
`webhook-signature`
- Signature header format: space-delimited list of versioned signatures;
symmetric signatures are `v1,<base64_hmac>` (standard alphabet, padded).
During zero-downtime secret rotation a match on *any* `v1` element is
accepted; non-`v1` elements (e.g. asymmetric `v1a`) are ignored, matching
the reference libraries' forward-compatible behavior.
- Signed string: `"{webhook-id}.{webhook-timestamp}.{raw_body}"` — literal
dot joins, with the id and timestamp taken verbatim from their headers
- Algorithm: HMAC-SHA256 over the signed string, base64-encoded
- Secret serialization: `whsec_`-prefixed base64; strip the prefix (if
present) and base64-decode — leniently, tolerating unpadded input and
non-canonical trailing bits as the official libraries do — before use as
the HMAC key. An empty or undecodable secret fails closed with
`InvalidSecret`.
- Replay protection required: reject when `|now - webhook-timestamp| >
max_age` (default 300s, matching the reference libraries' tolerance)
- Used by Svix, Clerk, Resend, and a growing list of adopters — implementing
this once covers all of them.
---
## 4. Security requirements (non-negotiable)
1. **Constant-time comparison.** All signature comparisons use
`subtle::ConstantTimeEq` (or equivalent) — never `==` on the decoded
bytes or the encoded strings.
2. **Verify against raw bytes only.** No implementation may re-serialize,
re-encode, or normalize the body before hashing. The `raw_body: &[u8]`
passed in is hashed exactly as received.
3. **No secret material in errors, logs, panics, or `Debug` output.**
Enforced by the `Secret` wrapper type and by a clippy lint / grep check
in CI (see §6).
4. **Reject on ambiguity, not accept.** If a header is present multiple
times with different values, or a required header is malformed, return
an error — never fall back to "treat as valid" behavior. The first-match
`HeaderMap` lookup cannot see duplicates, so framework adapters (the
`tower` and `actix` features) check the raw header map against the
provider's scheme-relevant signature headers before verifying; identical
repeats are not ambiguous and verify normally.
5. **No panics on attacker-controlled input.** Every parsing path
(`base64::decode`, `hex::decode`, header splitting, integer parsing of
timestamps) must return `Result`, not `unwrap()`/`expect()`, and this is
enforced by `#![deny(clippy::unwrap_used, clippy::expect_used)]` in the
provider modules.
6. **Timing of the whole function should not vary meaningfully based on
*why* verification failed.** Structurally this is hard to guarantee
perfectly (header lookups are not constant-time), but the security-
relevant step — signature comparison — must be, and is the one that
matters for known real-world timing attacks.
---
## 5. Testing bar for every provider
A provider implementation is not mergeable until it has:
1. **At least one official test vector**, sourced from the provider's own
docs/SDK/test suite, with a comment linking to the source.
2. **A negative test**: same inputs, one byte flipped in the signature →
must return `Err(VerifyError::SignatureMismatch)`.
3. **A tamper test**: valid signature, but `raw_body` modified after
signing → must fail.
4. **A replay test** (for providers with timestamps): valid signature, but
timestamp outside `max_age` → must return
`Err(VerifyError::TimestampOutOfTolerance { .. })`.
5. **A malformed-header test** for each required header: missing, empty,
and garbage-value cases each return a distinct, documented error variant
(never a panic, never `SignatureMismatch` masquerading as a parse
error).
6. **Fuzz coverage**: the header-parsing and encoding-decoding paths for
each provider are included in the shared `cargo fuzz` target
(`fuzz/fuzz_targets/parse_and_verify.rs`), which feeds arbitrary bytes as
headers/body and asserts only "no panic, no timeout" — correctness is
covered by the vector tests above, fuzzing exists purely to catch
panics/hangs on adversarial input.
7. **Constant-time assertion** where feasible: a `dudect`-style statistical
timing test on the comparison step, run in CI as a non-blocking
(informational) job given the inherent noise of CI runners.
---
## 6. CI requirements
- `cargo test --all-features` on stable, MSRV, and beta.
- `cargo clippy --all-features -- -D warnings`.
- `cargo fuzz build` (build-only in normal CI; timed fuzz runs in a
scheduled nightly job).
- A grep-based CI check that fails the build if any of `println!`,
`dbg!`, `log::`, or `tracing::` macros appear inside a `Secret`'s scope in
a way that could print its inner value (supplemented by the `Secret`
type's own redacted `Debug`/`Display` impls as the primary defense).
- `cargo semver-checks` against the last published version to catch
accidental breaking changes to the public API.
---
## 7. Open questions / future work
- **Certificate/public-key providers (PayPal, SendGrid).** *Resolved
(2026-08): caller-supplied key material only.* The crate never performs
network I/O — certificate fetching, URL allow-listing, and caching stay
with the caller. Rationale:
1. A fetcher inside `verify()` breaks two §1 goals at once ("no network
calls", "no required async runtime") and makes the security-critical
path impure and much harder to audit.
2. Trusting a cert URL is a deployment-specific decision (PayPal's
`Paypal-Cert-Url` must be validated against the caller's own
allowlist before use). Getting it wrong silently weakens verification
more thoroughly than any crypto bug; the crate should not make that
choice on callers' behalf.
3. A synchronous fetcher would drag in blocking HTTP + TLS dependencies;
an async one would force a runtime choice on all users.
Status: **SendGrid shipped (2026-09) behind `features = ["sendgrid"]`**
— `VerifyingKeyMaterial::EcdsaP256PublicKey`, the `verifying_material`
option, and the ECDSA P-256 verification path are implemented with the
provider's own test vector (see §3 SendGrid row). **PayPal shipped
(2026-10) behind `features = ["paypal"]`** — `X509Certificate`
certificate material, the `webhook_id` option, and the RSASSA-PKCS1-v1_5
SHA-256 verification path over the documented
`{transmission_id}|{transmission_time}|{webhook_id}|{crc32}` construction
(see §3 PayPal row; RFC 3339 transmission-time parsing lives in
`src/core/replay.rs`). The API shipped matches the 2026-08 sketch below
(with key/certificate bytes redacted from `Debug` output on the enum):
```rust
#[non_exhaustive]
pub enum VerifyingKeyMaterial {
X509Certificate(Vec<u8>),
EcdsaP256PublicKey(Vec<u8>),
}
pub struct VerifyOptions { pub verifying_material: Option<VerifyingKeyMaterial>,
pub webhook_id: Option<String>,
}
```
Error semantics (shipped and tested): required-but-absent
`verifying_material` fails closed with `MissingContext` (caller
misconfiguration, mirroring Square/Twilio); malformed material (bad
SPKI, wrong curve/algorithm) and a `X509Certificate` passed where
SendGrid requires a bare key fail with `InvalidSecret`; undecodable
base64 or non-DER signatures are `BadEncoding`; everything else is
`SignatureMismatch`.
Implementation notes: asymmetric verification uses feature-gated
RustCrypto dependencies (`p256`, optional `no_std`-compatible; `rsa` +
`x509-parser` + `crc32fast` behind the `paypal` feature — see the crate's
`Cargo.toml`). The
optional `webhook-verify-fetch` companion crate remains future work if
automated key rotation handling is ever requested — it stays out of this
crate either way.
- **Secret rotation UX.** *Resolved (2026-09, issue #64).* Stripe/Standard
Webhooks allow multiple valid signatures during a rotation window
(`v1=...,v1=...`). `verify()` keeps `Secret` singular in the core
signature for ergonomics (multi-`v1=` rotation lists remain accepted
inside a single `verify()`); cross-secret rotation ships as the
`verify_any(provider, headers, body, &[Secret], opts)` wrapper, whose
error-aggregation rules are a decision record in §2.
- **`no_std` scope.** Full `no_std` (no `alloc`) is likely infeasible given
base64/hex decoding and header string handling; target `no_std + alloc`
and validate against `wasm32-unknown-unknown` as the primary constrained
target (webhook verification at the edge, e.g. Cloudflare Workers via
`wasm-bindgen`, is a plausible real use case). *Implemented (issue #76):
the core is `no_std + alloc` behind the `std` feature (default on). Building
with `--no-default-features` drops the wall clock: [`Clock::now`] returns
unix seconds directly (no `SystemTime`), [`SystemClock`] is `std`-only, and
[`VerifyError`] does not implement `std::error::Error`. Callers on
bare-metal/wasm targets supply their own [`Clock`] for timestamped
(replay-protected) providers; a missing clock reads 0 and fail-closes replay
checks. Remaining work: a CI job (needs `.github/workflows/` write access) to
keep `--target wasm32-unknown-unknown --no-default-features` from
regressing.*
- **Provider promotion criteria.** A `CustomScheme` recipe gets promoted to
a first-class `Provider` variant once it has (a) official test vectors,
(b) at least one external user request or contribution, and (c) no open
design question from §7 blocking it.