#[non_exhaustive]pub struct VerifyOptions {
pub max_age: Option<Duration>,
pub clock: Option<Arc<dyn Clock>>,
pub request_url: Option<String>,
pub form_params: Option<Vec<(String, String)>>,
pub verifying_material: Option<VerifyingKeyMaterial>,
pub webhook_id: Option<String>,
}Expand description
Tuning knobs for crate::verify().
#[non_exhaustive]: new knobs are expected to arrive, and adding a field
must never break downstream callers. Outside this crate the fields are
therefore configured only through Default and the with_* builder
methods — struct-literal construction is intentionally unavailable.
use std::time::Duration;
use webhook_verify::VerifyOptions;
let opts = VerifyOptions::default().with_max_age(Some(Duration::from_secs(600)));
assert_eq!(opts.max_age, Some(Duration::from_secs(600)));Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.max_age: Option<Duration>Maximum allowed age between a signed timestamp and “now”, for providers
whose scheme includes a timestamp. None disables the check (not
recommended). Default: 300 seconds, matching Stripe’s and Slack’s own
SDK defaults.
Providers that do not sign timestamps document explicitly that this
option has no effect on them (see spec.md §3).
clock: Option<Arc<dyn Clock>>Clock used for “now”. None means real system time. Injectable for
deterministic tests of timestamp-based providers.
request_url: Option<String>Full URL of the receiving endpoint, required by providers whose signature incorporates it (currently Square, whose scheme signs the notification URL followed by the raw body, and Twilio, which signs the full request URL). The value must match the URL configured with the provider exactly — a differing trailing slash or scheme makes every signature fail. Providers whose scheme does not sign the URL document that this option has no effect on them.
Supplying the configured constant from the provider dashboard is the intended use; reconstructing the URL from request headers behind a proxy is a common source of verification failures.
form_params: Option<Vec<(String, String)>>Parsed application/x-www-form-urlencoded fields, required by Twilio:
its signature covers the request URL concatenated with the sorted
form-field names/values, not the raw body. Pass every field as
received — Twilio’s own docs warn against verifying against a hardcoded
subset, since providers may add parameters without notice. Sorting is
applied here (it is part of the signing scheme), so callers pass fields
in any order. A duplicate field name keeps its received relative order.
An explicitly empty list is meaningful (Twilio’s JSON-body variant signs
the URL alone); omitting the option entirely fails closed with
crate::VerifyError::MissingContext so a caller that forgot to parse
the body cannot be confused with an attacker-supplied input.
verifying_material: Option<VerifyingKeyMaterial>Verification material for providers whose scheme checks a signature
against a configured public key/certificate rather than a shared secret
(currently SendGrid and PayPal). See VerifyingKeyMaterial.
Required-but-absent fails closed with crate::VerifyError::MissingContext
(caller misconfiguration, mirroring Square/Twilio’s context options);
malformed material fails with crate::VerifyError::InvalidSecret.
This crate never fetches key material itself (spec.md §7): the caller
supplies bytes that were already obtained and vetted out-of-band.
webhook_id: Option<String>PayPal’s webhook ID, required by PayPal’s signed-string construction
(spec.md §3). It is not a request header or body field — it is the
ID of the webhook subscription (shown in the PayPal Developer Portal
for the listener URL) and must be supplied by the caller, mirroring
Square/Twilio’s URL context.
Required-but-absent for Provider::PayPal fails closed with
crate::VerifyError::MissingContext; an explicitly empty value is
treated the same way, so operator misconfiguration is never surfaced
as an attack-looking signature mismatch. Providers whose scheme does
not sign a webhook ID document that this option has no effect on them.
Implementations§
Source§impl VerifyOptions
impl VerifyOptions
Sourcepub fn with_request_url(self, url: impl Into<String>) -> Self
pub fn with_request_url(self, url: impl Into<String>) -> Self
Sets VerifyOptions::request_url, for URL-scoped schemes.
Sourcepub fn with_form_params<I, K, V>(self, params: I) -> Self
pub fn with_form_params<I, K, V>(self, params: I) -> Self
Sets VerifyOptions::form_params, for schemes that sign parsed form
fields (currently Twilio). Order does not matter; fields are sorted
into signing order during verification of Twilio’s signed string.
Sourcepub fn with_max_age(self, max_age: Option<Duration>) -> Self
pub fn with_max_age(self, max_age: Option<Duration>) -> Self
Sets VerifyOptions::max_age, the maximum allowed clock skew for
providers whose scheme signs a timestamp. None disables the check
(not recommended); the default is Some(Duration::from_secs(300)).
Providers that do not sign timestamps document explicitly that this
option has no effect on them (see spec.md §3).
Sourcepub fn with_clock(self, clock: Option<Arc<dyn Clock>>) -> Self
pub fn with_clock(self, clock: Option<Arc<dyn Clock>>) -> Self
Sets VerifyOptions::clock, the source of “now” used for replay
protection. None uses real system time. Injectable for deterministic
tests of timestamp-based providers.
Sourcepub fn with_verifying_material(self, material: VerifyingKeyMaterial) -> Self
pub fn with_verifying_material(self, material: VerifyingKeyMaterial) -> Self
Sets VerifyOptions::verifying_material, the asymmetric public-key
/certificate material required by public-key schemes (currently
SendGrid’s ECDSA P-256 key and PayPal’s X.509 certificate).
Sourcepub fn with_webhook_id(self, webhook_id: impl Into<String>) -> Self
pub fn with_webhook_id(self, webhook_id: impl Into<String>) -> Self
Sets VerifyOptions::webhook_id, PayPal’s webhook-subscription ID,
required by PayPal’s signed-string construction (see the field docs).