HookArmor 1.4: Webhook Replay Deduplication, AES-256 Body Encryption & The State of Webhook Infrastructure

In distributed SaaS architectures, webhooks are the single most vulnerable link in the payment and fulfilment chain. When a customer upgrades on Stripe, a merchant places an order on Shopify, or a payout triggers on Razorpay, your backend must guarantee two competing properties: never drop an event, and never execute duplicate side effects.

Today, we are announcing HookArmor v1.4.0, a major security and reliability upgrade. This release introduces cryptographic body-hash replay deduplication, opt-in AES-256-GCM payload encryption at rest, adaptive in-memory backpressure, and hard per-delivery deadlines.

In this deep dive, we break down why body-only signature schemes cause silent double-billing, how HookArmor v1.4.0 neutralizes these edge cases, and how HookArmor compares to commercial webhook platforms like Svix and Hookdeck.

The Vulnerability: The "Body-Only" Webhook Signature Trap

Every developer understands that webhooks must be verified against forgery using HMAC signatures. However, major payment and e-commerce gateways implement webhook signatures in fundamentally different ways:

• Header-Bound Signatures (Stripe, Svix/Clerk): Stripe signs both the raw payload body and a UNIX timestamp in the header (t=1697150000,v1=...). Because the timestamp is signed, an attacker cannot forge a new delivery time without invalidating the cryptographic signature.
• Body-Only Signatures (Shopify, GitHub, Razorpay): Shopify (X-Shopify-Hmac-Sha256) and Razorpay (X-Razorpay-Signature) compute the HMAC strictly over the raw request body. The delivery ID headers (such as X-Shopify-Webhook-Id or X-Razorpay-Event-Id) and HTTP timestamp headers are unsigned metadata.

How HookArmor 1.4 Solves It: Keyed Body-Hash Sliding Window

HookArmor v1.4.0 introduces an automated body-hash deduplication engine (HOOKARMOR_BODY_DEDUPE_HOURS, default 24h). When a cryptographically verified webhook arrives from a body-only provider (Shopify, GitHub, Razorpay):

1. HookArmor computes a canonical HMAC-SHA256 fingerprint over (provider, eventType, rawBodyBuffer).
2. Crucially, the eventType (e.g. Shopify topic orders/create vs orders/updated) is bound into the hash. This prevents false deduplication, as Shopify frequently sends byte-identical payloads across distinct lifecycle events.
3. If an identical verified payload has been received within the configured sliding window, HookArmor immediately returns HTTP 200 OK with status: "deduplicated" and the original hookarmor_id, suppressing the duplicate dispatch to your downstream backend.
4. Crucially, unverified webhooks cannot poison the deduplication cache. Even if an attacker spams arbitrary payloads, genuine verified events are never suppressed.

At-Rest Protection: AES-256-GCM Webhook Body Encryption

Webhook bodies contain your customers' most sensitive data: billing emails, credit card last4, shipping addresses, phone numbers, and invoice totals. While databases are often encrypted at the disk level, local SQLite WAL files, EBS volume snapshots, and container backups are frequently exported or shared across environments.

In HookArmor v1.4.0, setting HOOKARMOR_ENCRYPT_BODIES=true alongside your HOOKARMOR_ENCRYPTION_KEY activates binary AES-256-GCM envelope encryption at rest:

# Enable at-rest encryption in docker-compose.yml or .env
HOOKARMOR_ENCRYPTION_KEY=your-32-plus-character-secret-key-here
HOOKARMOR_ENCRYPT_BODIES=true

Every webhook body is sealed with a fresh 12-byte cryptographically secure random IV and authenticated with a 16-byte GCM authentication tag:

[ 12-byte IV ] [ 16-byte Auth Tag ] [ Ciphertext ]

Adaptive Memory Backpressure & Safe Event Parking

What happens when your production API goes down for 45 minutes during a flash sale? Under normal circumstances, webhook proxies keep piling up in-flight requests in memory. Once the Node.js event loop exceeds available RAM, the process crashes with an Out of Memory (OOM) error, incinerating every queued webhook in memory.

HookArmor v1.4.0 introduces Safe Event Parking (HOOKARMOR_MAX_QUEUED_IN_MEMORY=1000):

• When an endpoint reaches 1,000 queued deliveries in memory, HookArmor immediately parks subsequent events directly in SQLite with status = 'pending'.
• It answers the upstream gateway (Stripe/Shopify) with an immediate 200 OK so upstream providers never enter aggressive exponential backoff or disable your webhooks.
• The background retry worker sweeps parked events in batches (up to 1,000 events per 5s tick) and drains them asynchronously once your application stabilizes.
• Anti-Starvation: If one destination endpoint is down and backed up, HookArmor excludes it from the retry query, ensuring healthy endpoints are dispatched at full throughput without head-of-line blocking.

HookArmor vs. Svix vs. Hookdeck vs. DIY Queues

Engineering teams facing webhook reliability challenges typically evaluate four paths: commercial hosted SaaS (Svix, Hookdeck), rolling custom AWS SQS/Lambda infrastructure, or deploying HookArmor. Here is an honest, architectural comparison:

Why HookArmor's Architecture Wins for Modern SaaS

1. Zero Code Changes (Transparent Reverse Proxy): Hosted vendors like Svix require you to modify your application code, import proprietary SDKs, and redirect your entire webhook architecture to their APIs. HookArmor acts as a drop-in transparent proxy: your app still receives standard Stripe, Shopify, or Razorpay headers and authenticates them with standard HMAC verification libraries.
2. Zero-Dependency Lightweight Footprint: Unlike DIY distributed systems that require provisioning AWS SQS, DynamoDB, and Lambda concurrency limits, HookArmor is a single, statically deployable Node.js container with embedded SQLite WAL storage. It uses less than 80 MB of RAM, handles thousands of webhooks per second, and persists across reboots with a single Docker volume mount.
3. No Subscription SaaS Paywalls: Traditional webhook debuggers (Webhook.site, ngrok, Hookdeck) gate event replay history, custom headers, and multi-endpoint routing behind recurring monthly credit-card plans. HookArmor is 100% free and open-source under the MIT license.

Getting Started with HookArmor 1.4

You can run HookArmor in 10 seconds locally or deploy it to production on Railway, Render, or Docker:

# Run locally with zero install
npx hookarmor start

# Or deploy via Docker with persistent volume and body encryption
docker run -d \
  -p 4000:4000 \
  -v hookarmor_data:/app/data \
  -e HOOKARMOR_API_KEY=your-secret-api-key \
  -e HOOKARMOR_ENCRYPTION_KEY=your-32-char-encryption-key \
  -e HOOKARMOR_ENCRYPT_BODIES=true \
  --name hookarmor \
  ghcr.io/pkdoddamani/hookarmor:1.4.0