Expand description
§webhook-verify
One function to verify inbound webhook signatures from major providers.
Every backend that accepts webhooks ends up hand-rolling HMAC verification, and getting subtle details wrong: re-serialized bodies instead of raw bytes, non-constant-time comparison, missing replay protection, provider-specific encoding quirks. This crate does it once, correctly, behind a single API.
§Example: verifying a GitHub delivery
use webhook_verify::{verify, HeaderMap, Provider, Secret};
let headers: Vec<(String, String)> = vec![(
"X-Hub-Signature-256".to_string(),
"sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17".to_string(),
)];
let raw_body = b"Hello, World!";
let result = verify(
Provider::GitHub,
&headers,
raw_body,
&Secret::new("It's a Secret to Everybody"),
Default::default(),
);
assert!(result.is_ok());raw_body must be the exact bytes the provider sent — before any JSON
parsing or re-serialization. Verification against anything else will fail.
§Supported providers
A single Provider enum drives signature verification for:
| Provider | Scheme |
|---|---|
| Stripe | HMAC-SHA256 over timestamp.body, tolerance window |
| GitHub | HMAC-SHA256, X-Hub-Signature-256 |
| Shopify | HMAC-SHA256, base64 |
| Slack | HMAC-SHA256 v0= scheme + timestamp |
| Square | HMAC-SHA256 over notification URL + body, base64 |
| Twilio | HMAC-SHA1 over URL + sorted form params |
| Discord | Ed25519 public-key signatures (no shared secret) |
| PayPal | RSASSA-PKCS1-v1_5 SHA-256, X.509 cert + webhook ID |
| SendGrid | ECDSA P-256 over timestamp.body |
| Linear | HMAC-SHA256, linear-signature |
| Zoom | HMAC-SHA256 v0= scheme + timestamp |
| Dropbox | HMAC-SHA256, X-Dropbox-Signature |
| Standard Webhooks | HMAC-SHA256 with replay + rotation lists (Svix, Clerk, Resend, …) |
| Custom | User-supplied HMAC scheme via Provider::Custom |
PayPal and SendGrid ship behind crate features; calling verify() with
them while the feature is off fails closed with VerifyError::UnsupportedProvider.
§Crate features
std(default) — provides the wall clock used for replay protection and thestd::error::Errorimpl. Disable forno_std + alloctargets (validated againstwasm32-unknown-unknown); supply your ownClockfor timestamped providers.sendgrid— enables the SendGrid provider (ECDSA P-256).paypal— enables the PayPal provider (RSA, X.509, CRC-32).http—HeaderMapimpl forhttp::HeaderMap(axum, tower, hyper).tower— generictower::Layer/Servicemiddleware (works with axum routers too;httpis implied).actix— actix-web 4 extractor + header bridge.
See verify_any for cross-secret key rotation during a rotation window.
§Security properties
- All signature comparisons are constant-time (
subtle::ConstantTimeEq). - Bodies are hashed exactly as received; never re-encoded.
- No secret material ever appears in errors,
Debug, orDisplayoutput. - Parsing paths return
VerifyErrorinstead of panicking on attacker-controlled input.
Modules§
- actix
actix-web4 adapter: aFromRequestextractor that verifies inbound webhook signatures withcrate::verify()and yields the exact raw body bytes on success.- tower
- Generic
toweradapter: atower_layer::Layer/tower_service::Servicemiddleware that verifies inbound webhook signatures withcrate::verify()before the request reaches your handler.
Structs§
- Custom
Scheme - A user-configured HMAC verification scheme for providers not yet built in
(
spec.md§2.2). Also the prototyping shape new built-in providers are implemented against before promotion into theProviderenum. - Secret
- Wraps webhook signing material (an HMAC key, or — for asymmetric schemes such as Discord — a hex-encoded public key; see the provider’s docs for which one applies).
- System
Clock - The default
Clock: real wall-clock time. Only available under thestdfeature, which is on by default. - Verify
Options - Tuning knobs for
crate::verify().
Enums§
- Encoding
- Wire encoding of the signature in its header (
spec.md§2.2). - HashAlg
- HMAC hash algorithms available to a
CustomScheme(spec.md§2.2). - Provider
- A webhook provider whose signature scheme this crate knows how to verify.
- Verify
Error - Everything that can go wrong while verifying a webhook signature.
- Verifying
KeyMaterial - Caller-supplied asymmetric verification material (
spec.md§7).
Traits§
- Clock
- Source of “now”, injectable so replay-protection tests are deterministic.
- Header
Map - Case-insensitive, read-only header lookup.
Functions§
- verify
- Verifies that a webhook request was sent by
providerand was not tampered with in transit. - verify_
any - Tries multiple secrets during a zero-downtime rotation window.