Skip to main content
← Back to list
01Issue
FeatureOpenSwamp CLI
AssigneesNone

Relationships

#723 Data-driven webhook signature verifiers (avoid a code change + release per provider)

Opened by keeb · 6/20/2026

Background

Issue #716 adds pluggable webhook signature verification to swamp serve --webhook with a closed set of schemes (github, linear, stripe, slack, generic). Each named scheme is a hardcoded verifier in src/serve/.

Problem

With a closed enum, every new webhook provider that doesn't fit the limited generic (header + prefix over raw body) requires: a new bug report, a new verifier implementation in the swamp codebase, and a new swamp release. This makes swamp the maintenance owner of every provider's signature quirks.

Observation

Almost all webhook providers use the same primitive (HMAC over a constructed message) and differ only along a few axes:

  • signature header name
  • how the digest is extracted from the header value (prefix to strip, e.g. sha256=/v0=, or a keyed format e.g. stripe t=<ts>,v1=<hex>)
  • the signed-message template, e.g. github {body}, stripe {timestamp}.{body}, slack v0:{timestamp}:{body}
  • hash algorithm (sha256/sha1/sha512) and digest encoding (hex/base64)
  • optional timestamp source (separate header or embedded) + replay tolerance

Proposal to design

Make verification data-driven: one configurable HMAC engine parameterized by a declarative spec, with github/linear/stripe/slack shipped as built-in presets over that same engine. A brand-new HMAC provider would then be pure configuration — no swamp code change or release. Genuinely different mechanisms (asymmetric/RSA, JWT) remain out of scope (separate effort).

Open design questions: where the spec lives (CLI flag grammar vs config block vs extension), how expressive the message template should be, and how to keep it from becoming an over-engineered mini-language. A heavier alternative is a full verifier-extension plugin system.

This was split out of #716 so 716 can land the providers as the issue specified; the generalized/pluggable design is tracked here.

02Bog Flow
OPENTRIAGEDIN PROGRESSSHIPPED

Open

6/20/2026, 7:03:50 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.