Skip to main content

Crate webhook_verify

Crate webhook_verify 

Source
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:

ProviderScheme
StripeHMAC-SHA256 over timestamp.body, tolerance window
GitHubHMAC-SHA256, X-Hub-Signature-256
ShopifyHMAC-SHA256, base64
SlackHMAC-SHA256 v0= scheme + timestamp
SquareHMAC-SHA256 over notification URL + body, base64
TwilioHMAC-SHA1 over URL + sorted form params
DiscordEd25519 public-key signatures (no shared secret)
PayPalRSASSA-PKCS1-v1_5 SHA-256, X.509 cert + webhook ID
SendGridECDSA P-256 over timestamp.body
LinearHMAC-SHA256, linear-signature
ZoomHMAC-SHA256 v0= scheme + timestamp
DropboxHMAC-SHA256, X-Dropbox-Signature
Standard WebhooksHMAC-SHA256 with replay + rotation lists (Svix, Clerk, Resend, …)
CustomUser-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 the std::error::Error impl. Disable for no_std + alloc targets (validated against wasm32-unknown-unknown); supply your own Clock for timestamped providers.
  • sendgrid — enables the SendGrid provider (ECDSA P-256).
  • paypal — enables the PayPal provider (RSA, X.509, CRC-32).
  • http — HeaderMap impl for http::HeaderMap (axum, tower, hyper).
  • tower — generic tower::Layer/Service middleware (works with axum routers too; http is 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, or Display output.
  • Parsing paths return VerifyError instead of panicking on attacker-controlled input.

Modules§

actix
actix-web 4 adapter: a FromRequest extractor that verifies inbound webhook signatures with crate::verify() and yields the exact raw body bytes on success.
tower
Generic tower adapter: a tower_layer::Layer / tower_service::Service middleware that verifies inbound webhook signatures with crate::verify() before the request reaches your handler.

Structs§

CustomScheme
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 the Provider enum.
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).
SystemClock
The default Clock: real wall-clock time. Only available under the std feature, which is on by default.
VerifyOptions
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.
VerifyError
Everything that can go wrong while verifying a webhook signature.
VerifyingKeyMaterial
Caller-supplied asymmetric verification material (spec.md §7).

Traits§

Clock
Source of “now”, injectable so replay-protection tests are deterministic.
HeaderMap
Case-insensitive, read-only header lookup.

Functions§

verify
Verifies that a webhook request was sent by provider and was not tampered with in transit.
verify_any
Tries multiple secrets during a zero-downtime rotation window.