Webhook Signature Verification SDK: Language Libraries, Test Vectors & Interactive Verifier

[grantfox-oss]

Overview

Every developer who integrates Fluxa webhooks must implement HMAC-SHA256 signature verification. Getting this wrong means silently accepting forged webhook payloads — a critical security vulnerability. Fluxa currently documents the signature format in prose but provides no reference implementations. This issue produces official verification SDK snippets in five languages, a set of published test vectors (known payload + secret → known signature) that developers can use to validate their implementation, and an interactive verifier in the Fluxa dashboard.

What needs to be built

internal/webhook/ — Signature generation hardening

• Add: X-Fluxa-Timestamp header (Unix seconds at delivery time) — to prevent replay attacks
• Verification algorithm developers must implement:
  1. Check |now - X-Fluxa-Timestamp| < 300 (5-minute tolerance) — reject stale deliveries
  2. Construct signed_payload = X-Fluxa-Timestamp + "." + raw_body
  3. Compute expected = HMAC-SHA256(signed_payload, webhook_secret)
  4. Compare expected to X-Fluxa-Signature using a constant-time comparison
• Update all existing webhook deliveries to include X-Fluxa-Timestamp
docs/webhook-verification/ — Reference implementations

One file per language, each < 50 lines, production-quality:

• verify.ts — TypeScript (Node.js crypto module, no external dependencies)
• verify.py — Python (hmac + hashlib stdlib, no external dependencies)
• verify.go — Go (crypto/hmac + crypto/sha256 stdlib)
• verify.rb — Ruby (openssl stdlib)
• verify.php — PHP (hash_hmac + hash_equals)
  Each file includes: the verification function, inline comments explaining each step, a usage example, and a note about constant-time comparison and why it matters.

docs/webhook-verification/test-vectors.json

• 10 test vectors: { secret, timestamp, body, expectedSignature } — generated using the Fluxa reference implementation

• Vectors include: normal payload, empty body, Unicode body, large body (10KB), and a stale timestamp (> 5 minutes old, expected result: rejected)
  internal/webhook/ — API

• POST /v1/webhooks/verify — accepts { secret, timestamp, body, signature }; runs the verification algorithm; returns { valid: boolean, reason: string | null }; rate limited to 60 requests per minute per IP
  Dashboard — Webhook endpoint settings page

• "Verify Signature" tool: paste area for raw request headers (auto-extracts X-Fluxa-Signature and X-Fluxa-Timestamp), paste area for body, secret input (masked), "Verify" button

• Result: green "Valid" or red "Invalid" with the failure reason

• "Copy code snippet" button per language

Acceptance criteria

• All 5 language implementations produce the correct expectedSignature for all 10 test vectors — confirmed by running each implementation against the full vector set
• Stale timestamp (> 5 minutes) is rejected by the verification function in all 5 languages — not just by the API endpoint
• POST /v1/webhooks/verify correctly returns valid: false with reason: 'stale_timestamp' for a timestamp 6 minutes in the past
• All implementations use constant-time comparison — confirmed by code review (no string equality == on the signature values)
• X-Fluxa-Timestamp header is present on all new webhook deliveries — confirmed by inspecting the webhook_delivery_attempts table's stored headers
• Rate limit of 60 requests/minute is enforced — the 61st request within a minute returns 429

[nighshift-labs]

I inspected commit 9532d5394d0c0b498c1b5cdf35404835545f2660 and prepared a small, source-grounded first slice: a pure verifier plus table-driven Go tests for timestamp age, raw-body signing, malformed signatures, replay, Unicode, and constant-time comparison. The current Deliver path signs raw payload only and has no timestamp header, so changing it immediately would be a protocol compatibility break. Which bounded slice should be claimed first: (A) verifier + tests, (B) outbound timestamp/versioning, or (C) vectors/reference docs? I have not started code because CONTRIBUTING.md asks contributors to claim and wait for assignment.

[Jostel28]

'm an advanced Systems Engineering student with solid experience in backend architecture and script automation. I've reviewed the requirements and completely agree with @nighshift-labs about slicing this issue to avoid breaking current implementations prematurely. I would love to claim Slice (C): vectors and reference docs/snippets (or collaborate on any other slice needed). I'm highly comfortable implementing the strict cryptographic logic required for the snippets (like utilizing hmac.compare_digest in Python to guarantee constant-time verification) and generating the 10 test vectors. I will wait for your guidance and official assignment before writing code.

[wheval]

Hello , I’d like to work on this task because it combines security, backend API development, documentation, and developer experience. I can implement the HMAC-SHA256 verification flow with replay protection and constant-time comparison, add the timestamp header to webhook deliveries, create and validate the five production-ready language implementations and test vectors, and build the verification API and dashboard tool. I’ll also ensure the implementation is thoroughly tested against all acceptance criteria, including stale timestamps and rate limiting.

[grantfox-oss]

🦊 GrantFox — @wheval has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #72)
2. Your PR will be reviewed by the Savitura maintainers

Good luck! Track your progress on GrantFox.