Skip to main content

webhook_verify/
lib.rs

1//! # webhook-verify
2//!
3//! One function to verify inbound webhook signatures from major providers.
4//!
5//! Every backend that accepts webhooks ends up hand-rolling HMAC verification,
6//! and getting subtle details wrong: re-serialized bodies instead of raw bytes,
7//! non-constant-time comparison, missing replay protection, provider-specific
8//! encoding quirks. This crate does it once, correctly, behind a single API.
9//!
10//! ## Example: verifying a GitHub delivery
11//!
12//! ```no_run
13//! use webhook_verify::{verify, HeaderMap, Provider, Secret};
14//!
15//! let headers: Vec<(String, String)> = vec![(
16//!     "X-Hub-Signature-256".to_string(),
17//!     "sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17".to_string(),
18//! )];
19//! let raw_body = b"Hello, World!";
20//!
21//! let result = verify(
22//!     Provider::GitHub,
23//!     &headers,
24//!     raw_body,
25//!     &Secret::new("It's a Secret to Everybody"),
26//!     Default::default(),
27//! );
28//!
29//! assert!(result.is_ok());
30//! ```
31//!
32//! `raw_body` **must** be the exact bytes the provider sent — before any JSON
33//! parsing or re-serialization. Verification against anything else will fail.
34//!
35//! ## Supported providers
36//!
37//! A single [`Provider`] enum drives signature verification for:
38//!
39//! | Provider | Scheme |
40//! |---|---|
41//! | Stripe | HMAC-SHA256 over `timestamp.body`, tolerance window |
42//! | GitHub | HMAC-SHA256, `X-Hub-Signature-256` |
43//! | Shopify | HMAC-SHA256, base64 |
44//! | Slack | HMAC-SHA256 `v0=` scheme + timestamp |
45//! | Square | HMAC-SHA256 over notification URL + body, base64 |
46//! | Twilio | HMAC-SHA1 over URL + sorted form params |
47//! | Discord | Ed25519 public-key signatures (no shared secret) |
48//! | PayPal | RSASSA-PKCS1-v1_5 SHA-256, X.509 cert + webhook ID |
49//! | SendGrid | ECDSA P-256 over `timestamp.body` |
50//! | Linear | HMAC-SHA256, `linear-signature` |
51//! | Zoom | HMAC-SHA256 `v0=` scheme + timestamp |
52//! | Dropbox | HMAC-SHA256, `X-Dropbox-Signature` |
53//! | Standard Webhooks | HMAC-SHA256 with replay + rotation lists (Svix, Clerk, Resend, ...) |
54//! | Custom | User-supplied HMAC scheme via [`Provider::Custom`] |
55//!
56//! PayPal and SendGrid ship behind crate features; calling [`verify()`] with
57//! them while the feature is off fails closed with [`VerifyError::UnsupportedProvider`].
58//!
59//! ## Crate features
60//!
61//! - `std` *(default)* — provides the wall clock used for replay protection
62//!   and the `std::error::Error` impl. Disable for `no_std + alloc` targets
63//!   (validated against `wasm32-unknown-unknown`); supply your own [`Clock`]
64//!   for timestamped providers.
65//! - `sendgrid` — enables the SendGrid provider (ECDSA P-256).
66//! - `paypal` — enables the PayPal provider (RSA, X.509, CRC-32).
67//! - `http` — `HeaderMap` impl for `http::HeaderMap` (axum, tower, hyper).
68//! - `tower` — generic `tower::Layer`/`Service` middleware (works with axum
69//!   routers too; `http` is implied).
70//! - `actix` — actix-web 4 extractor + header bridge.
71//!
72//! See [`verify_any`] for cross-secret key rotation during a rotation window.
73//!
74//! ## Security properties
75//!
76//! - All signature comparisons are constant-time ([`subtle::ConstantTimeEq`]).
77//! - Bodies are hashed exactly as received; never re-encoded.
78//! - No secret material ever appears in errors, `Debug`, or `Display` output.
79//! - Parsing paths return [`VerifyError`] instead of panicking on
80//!   attacker-controlled input.
81//!
82//! [`subtle::ConstantTimeEq`]: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeEq.html
83
84#![forbid(unsafe_code)]
85#![deny(clippy::unwrap_used, clippy::expect_used)]
86#![warn(missing_docs)]
87#![cfg_attr(not(feature = "std"), no_std)]
88
89extern crate alloc;
90
91mod core;
92mod providers;
93
94#[cfg(test)]
95mod test_helpers;
96
97#[cfg(feature = "actix")]
98pub mod actix;
99
100#[cfg(feature = "tower")]
101pub mod tower;
102
103#[cfg(feature = "std")]
104pub use crate::core::SystemClock;
105pub use crate::core::{Clock, HeaderMap, Secret, VerifyError, VerifyOptions, VerifyingKeyMaterial};
106pub use crate::providers::{CustomScheme, Encoding, HashAlg, Provider, verify, verify_any};