Webhook verifier plugin · listing tai42/webhook-verifier-stripe
Install
Permissions
Provides
stripe
Webhook verifier — Verify a Stripe webhook delivery’s Stripe-Signature HMAC before dispatch.
Registers the stripe webhook verifier. It authenticates an inbound delivery’s
Stripe-Signature HMAC-SHA256 over {timestamp}.{raw body}, keyed by the endpoint’s
signing secret, and enforces a freshness window against replay. It is the verifier
binding behind the platform’s Stripe payments flow.
Bind it to a topic
A verifier is bound per hook topic. The binding names the environment variable that
holds the endpoint’s signing secret through config.secret_env — the verifier looks
that variable up at verify time, so the secret itself never lives in the manifest:
Set the signing secret from the Stripe dashboard webhook endpoint in that variable on
every process that receives deliveries:
The variable name is yours to choose — pick a distinct name per topic when one
deployment verifies several Stripe endpoints with different secrets.
Replay window
config takes an optional tolerance_seconds (a positive int, default 300), the
age past which a delivery is rejected:
Only a stale timestamp is rejected; a future timestamp is not, since sender clock skew
is not an attack signal.
Within that window the verifier also dedupes replays. After a delivery passes, its
Stripe event.id (the top-level evt_…) is claimed in a seen-set, so a captured signed
delivery replayed inside the window is refused rather than dispatched again.
The seen-set TTL runs until the signed freshness window ends (t + tolerance_seconds) —
anchored to the signed timestamp and rounded up so an id is never forgotten before that
window ends. tolerance_seconds is the knob that sets the window.
Behaviour
- Fails closed. A missing
secret_env key, a missing environment variable, an
empty secret, or a non-positive tolerance_seconds raises loudly rather than
degrading to an unauthenticated door. A malformed or mismatched signature is an
ordinary verification failure.
- Rotation-tolerant. A header may carry several
v1= digests during a secret
rotation; any one that matches passes, and a malformed candidate is dropped rather
than rejecting the delivery.
- Replay-deduped. A delivery that passes verification claims its
event.id in a
seen-set; a replay within the window is refused and nothing re-dispatches. The
seen-set TTL runs until the signed freshness window ends (t + tolerance_seconds).
- POST only. The signature covers the raw body, so a door binding this verifier
rejects GET.
See also
