webhook-verify 0.1.0

One function to verify inbound webhook signatures from major providers
Documentation
# webhook-verify

[![CI](https://github.com/AIUser91/useful-rust-crate-1/actions/workflows/ci.yml/badge.svg)](https://github.com/AIUser91/useful-rust-crate-1/actions/workflows/ci.yml)

**One function to verify inbound webhooks from any provider.**

Every backend that accepts webhooks ends up hand-rolling HMAC verification for
Stripe, GitHub, Shopify, Slack, and a dozen other services — and getting subtle
details wrong (raw body vs. re-serialized JSON, non-constant-time comparison,
missing replay protection, provider-specific encoding quirks). `webhook-verify`
is a small, dependency-light, audited-primitive-backed crate that does this
once, correctly, for every major provider, behind a single API.

```rust
use webhook_verify::{verify, Provider, Secret};

let headers: Vec<(String, String)> = vec![
    ("Stripe-Signature".to_string(), "t=1234567890,v1=abc...".to_string()),
];
let raw_body = b"{\"id\": \"evt_test\"}";

let result = verify(
    Provider::Stripe,
    &headers,        // anything implementing HeaderMap
    raw_body,         // &[u8] — MUST be the untouched request body
    &Secret::new(std::env::var("STRIPE_WEBHOOK_SECRET").expect("STRIPE_WEBHOOK_SECRET must be set")),
    Default::default(),
);

match result {
    Ok(()) => { /* trusted: safe to process the event */ }
    Err(e) => { /* reject with 400/401, log e */ }
}
```

That's it. No client SDK to pull in, no per-provider crate to learn, no
hand-copied signing-string logic to get wrong.

## Why this exists

- **The pain is universal.** Nearly every SaaS integrates *outbound* webhooks
  from payment processors, source control, chat platforms, and e-commerce
  tools. Verifying them correctly is small in code size but easy to get
  wrong, and wrong verification is a real security hole (forged
  `payment.succeeded` / `order.created` events).
- **Rust has no incumbent.** Go (`trusthook`) and TypeScript
  (`webhook-signature`, `hookinbox-verify`) both grew "one API, many
  providers" webhook verifiers in the last year. Rust still doesn't have one
  — only heavyweight per-vendor SDKs (`async-stripe`, `shopify-sdk`, ...)
  that happen to include verification as a minor feature, plus a handful of
  single-provider crates.
- **This should be a library, not a tutorial.** Search "verify \[provider\]
  webhook signature" for any provider and you'll find blog posts re-teaching
  the same HMAC recipe. That volume of repeated how-to content is the
  classic signal that the logic belongs in a dependency, not a copy-pasted
  snippet.

## Design principles

1. **Correctness over cleverness.** Every provider implementation is backed
   by test vectors taken from that provider's own documentation where they
   exist, and locally-constructed deterministic vectors over exactly the
   documented signed-string construction where a provider publishes none.
   No provider ships without them.
2. **No custom cryptography.** All primitives come from
   [RustCrypto]https://github.com/RustCrypto (`hmac`, `sha2`, `sha1`,
   `ed25519-dalek`, `subtle` for constant-time comparison). This crate only
   owns *parsing and orchestration*, never hashing or signature math.
3. **Headless core, thin adapters.** The value is in `verify()`, a pure,
   synchronous, allocation-light function. Framework integration (Axum,
   Actix Web, Tower) is optional sugar behind feature flags, not the point
   of the crate.
4. **Fail closed, explain why.** Errors are structured
   (`VerifyError::{MissingHeader, BadEncoding, SignatureMismatch,
   TimestampOutOfTolerance, UnsupportedProvider, ...}`) so callers can log
   and alert meaningfully instead of getting a bare `false`.
5. **No unbounded scope creep.** This crate verifies signatures. It does not
   deserialize event payloads, manage retries, store idempotency keys, or
   proxy webhooks. Those are separate, composable concerns (and separate
   crates) on purpose.

## Supported providers (target v0.1 matrix)

| Provider | Scheme | Status |
|---|---|---|
| GitHub | HMAC-SHA256, `X-Hub-Signature-256` | ✅ |
| Stripe | HMAC-SHA256 over `timestamp.body`, tolerance window | ✅ |
| Shopify | HMAC-SHA256, base64, `X-Shopify-Hmac-Sha256` | ✅ |
| Slack | HMAC-SHA256 `v0=` scheme, `X-Slack-Signature` + timestamp | ✅ |
| Linear | HMAC-SHA256, `linear-signature` | ✅ |
| Square | HMAC-SHA256 over notification URL + body, base64, `X-Square-HmacSha256-Signature` (needs `VerifyOptions::request_url`) | ✅ |
| Twilio | HMAC-SHA1 over URL + sorted form params, `X-Twilio-Signature` (needs `VerifyOptions::request_url` + `form_params`) | ✅ |
| Discord | Ed25519 (public-key), no shared secret | ✅ |
| PayPal | RSASSA-PKCS1-v1_5 SHA-256 over `transmission_id|time|webhook_id|crc32(body)`, X.509 cert + webhook ID via `VerifyOptions::verifying_material` + `webhook_id` (needs `paypal` feature) | ✅ |
| SendGrid | ECDSA P-256 over `timestamp.body`, public key via `VerifyOptions::verifying_material` (needs `sendgrid` feature) | ✅ |
| Zoom | HMAC-SHA256, `v0=` scheme, `x-zm-signature` + timestamp | ✅ |
| Dropbox | HMAC-SHA256, `X-Dropbox-Signature` | ✅ |
| Standard Webhooks spec (Svix, Clerk, Resend, ...) | HMAC-SHA256, `webhook-signature` (`v1,` base64, rotation list) + replay window | ✅ |
| Custom | User-supplied HMAC scheme via `Provider::Custom(..)` (SHA-256/SHA-1/SHA-512, hex/base64, optional prefix + timestamp replay window) | ✅ |

Some providers ship behind crate features: calling `verify()` on `PayPal`
or `SendGrid` without the corresponding feature compiled in fails closed
with `VerifyError::UnsupportedProvider`. See [`spec.md`](./spec.md) for the
exact signed-string construction, header names, and encoding for each
provider, and the process for adding new ones.

SendGrid verification is compiled only with the crate feature:

```toml
[dependencies]
webhook-verify = { version = "0.1", features = ["sendgrid"] }
```

For `no_std + alloc` targets, keep `default-features = false` together with
`features = ["sendgrid"]`.

PayPal verification is compiled only with the crate feature:

```toml
[dependencies]
webhook-verify = { version = "0.1", features = ["paypal"] }
```

It verifies against the caller-supplied certificate (the crate never fetches
`PayPal-Cert-Url` — see `spec.md` §7) and needs both the webhook
subscription ID and the certificate to be configured:

```rust,ignore
let opts = VerifyOptions::default()
    .with_webhook_id("your-webhook-subscription-id")
    .with_verifying_material(VerifyingKeyMaterial::X509Certificate(cert_pem_bytes.to_vec()));

let result = verify(Provider::PayPal, &headers, raw_body, &Secret::new("unused"), opts);
```

## Secret rotation

During a signing-key rotation window, Stripe and other standard-webhook
providers accept requests signed by either the old or the new key.
`verify_any()` tries each secret in turn and accepts the request if any one
of them verifies:

```rust,ignore
use webhook_verify::{verify_any, Provider, Secret};

let result = verify_any(
    Provider::Stripe,
    &headers,
    raw_body,
    &[Secret::new(new_secret), Secret::new(old_secret)],  // try new first
    Default::default(),
);
```

- A match on **any** key returns `Ok(())`; the request is safe to process.
- Structural errors (`MissingHeader`, `MalformedHeader`, `BadEncoding`,
  `UnsupportedProvider`, `MissingContext`, `TimestampOutOfTolerance`) are
  deterministic across all secrets and return immediately.
- A garbled/undecodable key (`InvalidSecret`) does **not** abort the search —
  a still-healthy key later in the slice can verify. If every key is
  well-formed but wrong, you get `SignatureMismatch`; only when *every* key
  is malformed do you get `InvalidSecret` (an operator-configuration signal,
  not a forgery). Full decision record in `spec.md` §2.1.

## Installation

```toml
[dependencies]
webhook-verify = "0.1"

# verify straight against http::HeaderMap (axum, tower, hyper, ...)
webhook-verify = { version = "0.1", features = ["http"] }

# generic tower middleware (works with axum routers too)
webhook-verify = { version = "0.1", features = ["tower"] }

# actix-web 4 extractor + header bridge
webhook-verify = { version = "0.1", features = ["actix"] }
```

With the `http` feature enabled, any `http::HeaderMap` (from axum, tower, or
hyper requests) implements `HeaderMap` and can be passed to `verify()` directly.

### `no_std` support

The core verification path is `no_std + alloc` compatible (validated against
`wasm32-unknown-unknown`). The `std` feature (on by default) provides the wall
clock used for replay protection and the `std::error::Error` impl. Disable it
for constrained targets:

```toml
# no wall clock; supply your own Clock for timestamped providers
webhook-verify = { version = "0.1", default-features = false }
```

Without `std`, [`Clock::now`] returns unix seconds directly, `SystemClock` is
unavailable, and `VerifyError` does not implement `std::error::Error` — see
`spec.md` §7.

## Framework adapters

### Tower (also Axum)

`webhook-verify::tower::VerifyLayer` is a generic `tower::Layer`. It buffers
the request body as raw bytes, rejects requests whose signature headers arrive
duplicated with conflicting values (`400`, see spec §4.4), verifies with
`verify()`, and forwards the exact buffered bytes downstream — handlers can
then deserialize freely. Verification failures never reach your handler:

| Failure class | Status |
|---|---|
| Missing / malformed signature headers | `400 Bad Request` |
| Signature mismatch / stale timestamp | `401 Unauthorized` |
| Operator misconfiguration | `500 Internal Server Error` |

Plain tower stacks receive `Request<Bytes>`; axum users get their own body
type back automatically via type inference:

```rust
use webhook_verify::{Provider, Secret};
use webhook_verify::tower::VerifyLayer;

let layer = VerifyLayer::new(Provider::Stripe, secret);

// Plain tower: inner service takes http::Request<Bytes>.
let svc = layer.clone().layer(my_handler_service);

// Axum: same layer, inferred as axum::body::Body.
// Router::new()
//     .route("/webhooks/stripe", post(handle_stripe))
//     .layer(layer);
```

#### Axum

Axum routers are tower services, so `VerifyLayer` is the supported axum
integration — no separate feature or module is needed:

```rust,ignore
use axum::{routing::post, Router};
use webhook_verify::{Provider, Secret};
use webhook_verify::tower::VerifyLayer;

let app = Router::new()
    .route("/webhooks/github", post(handle_github))
    .layer(VerifyLayer::new(Provider::GitHub, Secret::new(secret)));
```

The layer buffers and verifies the raw body before routing, so handlers can
use extractors freely (`Json`, `Bytes`, ...) — the bytes they receive are
already verified.

> ⚠️ **If you bypass the middleware**, verify before any extractor touches the
> body. Extractors run top-down and body-consuming ones (`Json`, `Bytes`,
> `String`) drain the request; once they have run, the original wire bytes are
> gone. Capture the body first (e.g. `Bytes` as your first extractor), call
> `verify()` on those exact bytes with an `http::HeaderMap` (the `http`
> feature), and only then deserialize a copy.

### Actix Web

Enable the `actix` feature and register a `WebhookConfig` on your app; the
`VerifiedBody` extractor then verifies the signature and hands your handler
the exact raw bytes:

```rust,ignore
use actix_web::{App, HttpResponse, web};
use webhook_verify::actix::{VerifiedBody, WebhookConfig};
use webhook_verify::{Provider, Secret};

App::new()
    .app_data(WebhookConfig::new(Provider::GitHub, Secret::new(secret)))
    .route(
        "/webhooks/github",
        web::post().to(|body: VerifiedBody| async move {
            // `body` is the exact wire payload, already verified.
            HttpResponse::Ok().finish()
        }),
    );
```

Because actix-web 4 reads the body only during extraction, `VerifiedBody`
captures it *before* anything else can touch it — do **not** also take
`web::Json<T>` in the same handler (extractors run left-to-right and `Json`
would consume the body first); deserialize from `body`'s exact bytes instead.
Requests whose scheme headers arrive duplicated with conflicting values are
rejected with `400` before verification (spec §4.4). Failure statuses match
the tower table above. A guard is intentionally not provided: guards run
before the body is read, but verification requires those bytes.

> ⚠️ **Raw body required.** All frameworks buffer and re-parse JSON by
> default, which changes byte-for-byte content (key ordering, whitespace).
> The tower adapter and actix extractor capture the exact bytes off the wire
> before anything else touches them; if you call `verify()` directly instead,
> make sure you pass those same untouched bytes (with the `http` feature for
> axum/tower/hyper maps, or the bridge provided by the `actix` feature).

## Security notes

- All signature comparisons use constant-time equality (`subtle::ConstantTimeEq`).
- Timestamp-based replay protection is enabled by default wherever the
  provider supports it (`VerifyOptions::max_age`, default 5 minutes).
- This crate does not log secrets, request bodies, or computed signatures
  under any log level.
- Secrets are wrapped in a `Secret` type that redacts `Debug`/`Display` output.

## Non-goals

- Sending/registering webhooks (that's the provider's own SDK's job).
- Event payload parsing/typing.
- Idempotency / deduplication of already-verified events.
- A hosted or proxying service (this is a plain library).

## Versioning & MSRV

Semantic versioning. New providers are additive (minor version bumps).
Changes to an existing provider's verification logic that could reject
previously-accepted requests are treated as breaking (major version bump),
except where required to fix a genuine security defect, which will be
called out explicitly in the changelog and a security advisory.

MSRV: **1.85** (first Rust release with edition 2024 support), checked in CI.

## Contributing

New providers, corrected test vectors, and encoding edge cases are the
highest-value contributions. See [`AGENTS.md`](./AGENTS.md) for the
step-by-step process (used by both human and AI contributors) and
[`spec.md`](./spec.md) for the technical contract each provider
implementation must satisfy.

## License

Dual-licensed under MIT or Apache-2.0, at your option.