DEV Community: EventDock

How to Verify Shopify Webhook Signatures (and the Base64 Raw-Body Trap)

EventDock — Mon, 20 Jul 2026 16:14:52 +0000

Shopify webhook verification fails for two reasons more than any other, and both come from habits that work everywhere else. The signature is base64, not the hex string Stripe and GitHub hand you, and Shopify's own quickstart parses the body with express.json() before you get a chance to hash the bytes it actually signed. Get either wrong and your comparison never matches even though your code looks right. This post shows the exact Shopify webhook check, which secret to use, and the traps that account for most of the failures.

The exact scheme

Per Shopify's docs, each webhook request carries an HMAC in the X-Shopify-Hmac-Sha256 header. It is HMAC-SHA256 computed over the raw request body, keyed with your app's client secret, and the result is base64-encoded. Three details decide whether your check works: the raw body, the client secret, and base64.

Verifying the signature

Compute the HMAC over the untouched body, base64-encode it, and compare it to the header in constant time.

const crypto = require('crypto');

// Your app's client secret: Partner Dashboard > your app > API credentials
const CLIENT_SECRET = process.env.SHOPIFY_API_SECRET;

function isValidShopifyWebhook(rawBody, hmacHeader) {
  const digest = crypto
    .createHmac('sha256', CLIENT_SECRET)
    .update(rawBody)              // the raw bytes, not a re-serialized object
    .digest('base64');           // base64, NOT hex

  const a = Buffer.from(digest);
  const b = Buffer.from(hmacHeader || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: capture the RAW body, verify, then parse
app.post('/webhooks/shopify',
  express.raw({ type: '*/*' }),
  (req, res) => {
    const rawBody = req.body;     // Buffer, untouched
    const hmac = req.get('X-Shopify-Hmac-Sha256');

    if (!isValidShopifyWebhook(rawBody, hmac)) {
      return res.status(401).send('invalid hmac');
    }

    const payload = JSON.parse(rawBody.toString('utf8'));  // parse only after
    const topic = req.get('X-Shopify-Topic');              // e.g. orders/create
    // ... handle the event
    res.sendStatus(200);
  });

The comparison uses crypto.timingSafeEqual rather than ===, because a plain string compare returns early on the first differing byte and leaks timing. Guard the length first, since timingSafeEqual throws when the two buffers differ in length. Shopify expects a fast 200 on success and treats a non-2xx as a failed delivery, so respond with 401 when the HMAC does not match and keep the handler quick.

The raw-body trap

HMAC signs bytes, not objects. If a JSON body parser runs first and you rebuild a string from the parsed object to verify against, the bytes are no longer identical to what Shopify sent. Whitespace and key order shift and the signature never matches. This one bites Shopify developers especially often because the platform's introductory tutorials wire up express.json() at the top of the app, which consumes and reparses the body before your webhook route runs. Put the raw capture on the webhook route itself with express.raw(), verify against the Buffer, and call JSON.parse only after the check passes. It is the same trap Stripe, Paddle, and most others share, laid out in the webhook signature verification comparison.

Base64, not hex

Most signature guides you have read, including for Stripe and GitHub, end in .digest('hex'). Shopify does not. It base64-encodes the HMAC, so the header looks like XWJ...= with mixed case and often a trailing =, not a long run of lowercase hex. If you copy verification code from a Stripe example and only change the header name and secret, the digest encoding stays hex and every Shopify comparison fails. Change hex to base64 and the same code starts matching. When you compare, compare like to like: base64 digest against the base64 header, or decode both to bytes first, but do not mix one of each.

Which secret Shopify signs with

The signing key is your app's client secret, the same value you use in the OAuth flow, found under API credentials in the Partner Dashboard. Reach for the wrong value and every check fails, and there are a few wrong values sitting right next to it. The client secret is not your API access token, and it is not the API key that pairs with it, it is the secret. If you run more than one app, or a development app alongside a production one, each has its own client secret, so a webhook delivered under one app verified with the other app's secret will never match. When verification fails and you are sure the body and the encoding are right, the secret is the next thing to check.

The mistakes that account for most failures

Encoding the digest as hex instead of base64.
Verifying against a re-serialized body instead of the raw bytes, usually because express.json() ran first.
Using the wrong secret: the API access token or API key instead of the client secret, or another app's client secret.
Comparing with === instead of a constant-time function.
Testing against one store or app and shipping with a different app's credentials, so the secret no longer matches.

Signatures do not cover the events you never receive

A valid HMAC proves a webhook really came from Shopify. It does nothing for the orders/create or app/uninstalled event that never arrives because your server was mid-deploy, timed out under load, or threw before it acknowledged. Shopify retries a failed delivery 8 times over about 4 hours, and for a subscription created through the Admin API it deletes the subscription after 8 consecutive failures, so a bad stretch does not just lose events, it can switch the topic off entirely, and the events behind it are orders, refunds, and fulfillments, the ones you least want to miss.

That is the layer EventDock adds. You point Shopify at EventDock instead of your app. EventDock verifies the signature against the raw body, stores the event, and acknowledges Shopify right away so no timeout or downtime window costs you a delivery, then forwards it to your app with its own retries and a dead-letter queue you can replay by hand. If your app is down for an hour, the events wait and arrive when it recovers instead of counting toward the failure threshold that disables the topic. For the duplicate deliveries any retrying pipeline produces, the exactly-once processing pattern keeps your handler idempotent.

You can point a Shopify test webhook at EventDock on the free tier and watch every event get verified, stored, and delivered. Start with EventDock free.

How to Verify Razorpay Webhook Signatures (and Why It Is Not the Payment Signature)

EventDock — Thu, 16 Jul 2026 05:32:39 +0000

Razorpay trips people up in a way most providers do not: it has two separate signatures that use the same algorithm but different keys and different inputs, and they are easy to confuse. One verifies webhooks. The other verifies a checkout payment on your success handler. Sign the wrong thing with the wrong secret and your verification fails while your code looks correct. This post shows the exact Razorpay webhook verification, the raw-body trap, and how the webhook signature differs from the payment signature.

First: Razorpay has two different signatures

Both are HMAC-SHA256 and both end up as a hex string, which is exactly why they get mixed up. But they are not interchangeable:

Webhook signature arrives in the X-Razorpay-Signature header on webhook requests. It is keyed with your webhook secret and computed over the raw request body.
Payment signature comes back as razorpay_signature in the Checkout success handler, alongside razorpay_order_id and razorpay_payment_id. It is keyed with your API key secret and computed over order_id + "|" + payment_id.

If you verify a webhook using the key secret, or verify a payment using the webhook secret, every check fails. Keep them straight and most Razorpay signature pain disappears.

Verifying the webhook signature

Per Razorpay's docs, the webhook hash is HMAC-SHA256 with your webhook secret as the key and the raw webhook body as the message, hex-encoded, delivered in X-Razorpay-Signature.

const crypto = require('crypto');

// Set when you created the webhook in the Razorpay Dashboard
const WEBHOOK_SECRET = process.env.RAZORPAY_WEBHOOK_SECRET;

function isValidRazorpayWebhook(rawBody, signatureHeader) {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)              // the raw bytes, not a re-serialized object
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: capture the RAW body, verify, then parse
app.post('/webhooks/razorpay',
  express.raw({ type: '*/*' }),
  (req, res) => {
    const rawBody = req.body;     // Buffer, untouched
    const signature = req.get('X-Razorpay-Signature');

    if (!isValidRazorpayWebhook(rawBody, signature)) {
      return res.status(400).send('invalid signature');
    }

    const event = JSON.parse(rawBody.toString('utf8'));  // parse only after
    // ... handle event.event (payment.captured, order.paid, etc.)
    res.json({ status: 'ok' });
  });

The raw-body trap

HMAC signs bytes, not objects. If a JSON body parser runs first and you rebuild a string from the parsed object to verify against, the bytes are no longer identical to what Razorpay sent. Whitespace and key order shift and the signature never matches. Capture the raw, unparsed body, verify against it, and parse only after the check passes. In Express that means express.raw() on the webhook route rather than express.json(). This is the same trap Stripe, Paddle, and most others share, laid out in the webhook signature verification comparison.

The payment signature is a different check

When Checkout finishes, the handler gives you razorpay_order_id, razorpay_payment_id, and razorpay_signature. This is not a webhook, and it is not verified with the webhook secret. You recompute it with your API key secret over the two IDs joined by a pipe.

// Checkout success verification (NOT the webhook path)
const expected = crypto
  .createHmac('sha256', process.env.RAZORPAY_KEY_SECRET)   // API key secret here
  .update(razorpay_order_id + '|' + razorpay_payment_id)   // the two IDs, pipe-joined
  .digest('hex');

const ok = expected === razorpay_signature;  // compare to the checkout field

Same algorithm, different key, different message. Treat the webhook path and the payment path as two separate verifications and do not share a secret between them.

The mistakes that account for most failures

Verifying the webhook with the API key secret instead of the per-webhook secret.
Verifying against a re-serialized body instead of the raw bytes.
Reusing the payment-signature logic (order_id|payment_id) to check a webhook, or vice versa.
Comparing with === instead of a constant-time function.
Using a test-mode webhook secret against live traffic, or the reverse.

Signatures do not cover the events you never receive

A valid signature proves a webhook really came from Razorpay. It does nothing for the payment.captured or order.paid event that never arrives because your server was mid-deploy, timed out under load, or threw before it acknowledged. Razorpay retries failed webhooks for a while, but retries only help if your endpoint comes back before they stop, and the events behind them are payments, refunds, and settlements, the ones you least want to lose.

That is the layer EventDock adds. You point Razorpay at EventDock instead of your app. EventDock verifies the signature, stores the event, and acknowledges Razorpay right away so no timeout or downtime window costs you a delivery, then forwards it to your app with its own retries and a dead-letter queue you can replay by hand. If your app is down for an hour, the events wait and arrive when it recovers. For the duplicate deliveries any retrying pipeline produces, the exactly-once processing pattern keeps your handler idempotent.

You can point a Razorpay test webhook at EventDock on the free tier and watch every event get verified, stored, and delivered. Start with EventDock free.

How to Verify Square Webhook Signatures (and the Notification-URL Trap)

EventDock — Tue, 14 Jul 2026 10:55:28 +0000

Square's webhook signature catches people in a specific way: the signature is computed over the notification URL joined to the raw request body, not the body on its own. Miss the URL, or reconstruct a URL that differs by even a trailing slash, and every notification fails validation while your HMAC code looks perfectly correct. This post shows the exact scheme Square uses, the two traps that break it, and the older header you should stop trusting.

What Square actually signs

Every webhook from Square carries an x-square-hmacsha256-signature header. Per Square's own validation docs, the value is an HMAC-SHA-256 built from three things:

The signature key for your webhook subscription (found next to the subscription in the Square Dashboard, one per subscription).
The notification URL you configured for that subscription.
The raw body of the request, exactly as sent.

The message you run through HMAC is the notification URL followed by the raw body, concatenated in that order, and the result is Base64-encoded. To validate, you compute the same thing and compare it against the header.

const crypto = require('crypto');

// From your webhook subscription in the Square Dashboard
const SIGNATURE_KEY = process.env.SQUARE_SIGNATURE_KEY;

// The EXACT notification URL you configured for the subscription
const NOTIFICATION_URL = 'https://api.yourapp.com/webhooks/square';

function isValidSquareSignature(rawBody, signatureHeader) {
  const payload = NOTIFICATION_URL + rawBody;   // URL first, then the raw body
  const expected = crypto
    .createHmac('sha256', SIGNATURE_KEY)
    .update(payload, 'utf8')
    .digest('base64');

  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: capture the RAW body, verify, then parse
app.post('/webhooks/square',
  express.raw({ type: '*/*' }),
  (req, res) => {
    const rawBody = req.body.toString('utf8');
    const signature = req.get('x-square-hmacsha256-signature');

    if (!isValidSquareSignature(rawBody, signature)) {
      return res.status(403).send('bad signature');
    }

    const event = JSON.parse(rawBody);   // only parse after the check passes
    // ... handle event
    res.sendStatus(200);
  });

Notice the comparison uses crypto.timingSafeEqual rather than ===. A plain string compare returns early on the first differing byte, and that timing difference leaks how much of the signature you got right. Use a constant-time compare, and guard the length first because timingSafeEqual throws on a length mismatch.

Trap one: the raw body

HMAC signs bytes, not objects. If your framework parses the JSON and you rebuild a string from the parsed object to verify against, the bytes are no longer identical to what Square sent. Key order, whitespace, and number formatting all shift, and the signature never matches. Capture the raw, unparsed body, verify against it, and parse only after the check passes. In Express that means express.raw() on the webhook route, not express.json(). This is the same trap Stripe, Paddle, HubSpot, and Slack share, laid out side by side in the webhook signature verification comparison.

Trap two: the notification URL has to match exactly

Because the URL is part of the signed message, the string you concatenate has to be the exact notification URL Square has on file for the subscription, character for character. This is where most Square-specific failures come from:

Reconstructing the URL from the request. If you build the URL from req.protocol and req.headers.host, a load balancer that terminates TLS can hand your app http instead of https, or a different host, and your rebuilt URL stops matching. Do not rebuild it. Use the exact URL you registered, as a constant.
Trailing slash and path differences. https://api.yourapp.com/webhooks/square and the same URL with a trailing slash produce different signatures. Match what is stored in the subscription exactly.
Sandbox versus production. The two environments have separate subscriptions, separate signature keys, and usually separate notification URLs. Verifying a sandbox event against your production key and URL fails every time.

The clean fix is to treat the notification URL as a known constant per environment rather than something you derive at request time. You configured it, so you already know it. This is the same class of problem Twilio has, where the signature is tied to the request URL and a proxy can break it, covered in the Twilio signature validation guide.

Stop using the legacy x-square-signature header

Older Square integrations validated an x-square-signature header that used HMAC-SHA1. That scheme is legacy and being retired in favor of the SHA-256 header above. If your code still reads x-square-signature, move to x-square-hmacsha256-signature. SHA1 is not a hash you want at the door of your payment events, and Square's current guidance is to use the SHA-256 signature.

The mistakes that account for most failures

Signing the body only and forgetting to prepend the notification URL.
Verifying against a re-serialized body instead of the raw bytes.
Rebuilding the URL from request headers behind a proxy instead of using the configured constant.
Using the wrong subscription's signature key, or crossing sandbox and production keys.
Comparing with === instead of a constant-time function.

Signatures are only half of it

Validating the signature proves a notification really came from Square. It does nothing for the notification that never arrives, the one that fired while your server was mid-deploy, or the one dropped because your handler threw before it acknowledged. Square retries failed deliveries for a while and then disables the subscription if it keeps failing, so a bad hour on your side can turn into a subscription Square has stopped sending to. The events behind that are the ones tied to money, a payment completed, a refund, a dispute, exactly the ones you cannot afford to lose.

That is the layer EventDock adds. You point Square at EventDock instead of your app. EventDock verifies the signature, stores the event, and acknowledges Square right away so no timeout or downtime window costs you a delivery, then forwards it to your app with its own retries and a dead-letter queue you can replay by hand. If your app is down for an hour, the events wait and arrive when it recovers instead of being dropped and eventually disabled. For the duplicate deliveries any retrying pipeline produces, the exactly-once processing pattern covers how to stay idempotent.

You can point a Square sandbox subscription at EventDock on the free tier and watch every event get verified, stored, and delivered. Start with EventDock free.

Hookdeck vs EventDock: Pricing, Features & Real Tests (2026)

EventDock — Tue, 14 Jul 2026 08:40:09 +0000

If you've ever had a webhook silently fail at 2 AM, you know the pain. You need a reliability layer between the provider and your server. The question is: which one?

Hookdeck and EventDock both solve this problem, but they take very different approaches. This is an honest comparison to help you choose.

The Problem: Webhooks Are Fragile

Webhooks are the backbone of modern integrations. Stripe sends payment events, Shopify sends order updates, GitHub sends push notifications. But webhooks have a fundamental flaw: they assume your server is always available, always fast, and always correct.

In reality:

Servers go down for deploys, scaling events, or outages
Endpoints time out under load
Bugs cause 500 errors that silently swallow events
Providers retry with exponential backoff — then give up forever

A webhook reliability platform sits between the provider and your server. It accepts webhooks on your behalf, stores them durably, and delivers them with retries, monitoring, and replay.

What Hookdeck Does

Hookdeck is a well-established webhook infrastructure platform. Credit where it's due — they've built a comprehensive system with a strong feature set:

Connections model: You create Sources (webhook origins) and Destinations (your endpoints), then wire them together with Connections. This gives you flexible routing — one source can fan out to multiple destinations.
Transformations: JavaScript functions that modify webhook payloads in-flight. Useful for reformatting data between systems.
Filtering: Rules to drop or route webhooks based on payload content, headers, or other criteria.
CLI tool: Local development tunnel for testing webhooks against your local server.
Enterprise routing: Advanced features for high-volume, multi-tenant webhook architectures.

Hookdeck is a powerful system. If you need complex webhook orchestration — transforming payloads, routing to multiple services, building event-driven pipelines — it's a solid choice.

What EventDock Does Differently

EventDock takes a different philosophy: webhook reliability should be simple, fast, and predictable.

Simpler Mental Model

No connections, sources, or destinations to configure. You create an endpoint, get a URL, point your provider at it, and set your destination. Done. EventDock focuses on doing one thing well: making sure your webhooks arrive reliably.

Edge-Native Architecture

EventDock runs on Cloudflare Workers — your webhooks are received at the edge location closest to the provider, anywhere in the world. This means sub-100ms global ingest latency. Your provider gets a fast 200 response, and EventDock handles delivery to your server in the background.

Flat, Predictable Pricing

No per-event billing that scales unpredictably. You pick a plan, you know what you pay. No surprises when a provider sends a burst of retry events.

Automatic Signature Verification

EventDock verifies webhook signatures from major providers (Stripe, Shopify, GitHub, and more) automatically. Spoofed webhooks are rejected before they ever reach your server.

Dead Letter Queue with One-Click Replay

When webhooks fail after all retries, they go to a dead letter queue. You can inspect the full payload, fix the issue on your end, and replay with a single click from the dashboard.

Free Webhook Endpoint Tester

A free tool at eventdock.app/tools/webhook-tester that lets you inspect incoming webhooks in real time. No signup required.

Feature Comparison

Feature	EventDock	Hookdeck
Automatic retries	Yes (7 attempts, exponential backoff)	Yes (configurable)
Dead letter queue	Yes, with one-click replay	Yes
Signature verification	Automatic for major providers	Manual configuration
Idempotency / deduplication	Built-in (24h window)	Yes
Real-time dashboard	Yes	Yes
Payload transformations	No	Yes
Fan-out routing	No	Yes (Connections model)
Filtering rules	No	Yes
CLI / local tunnel	Yes	Yes
Edge-native (global PoPs)	Yes (Cloudflare Workers)	No (centralized)
Setup time	~2 minutes	~10 minutes
Alerts (Slack, email)	Yes	Yes

Pricing Comparison

Plan	EventDock	Hookdeck
Free tier	5,000 events/month, 3 endpoints	100,000 events/month
Entry tier	\$29/mo — 20,000 events, 10 endpoints	Growth: \$0.20 per 1,000 events
Mid tier	\$149/mo — 50,000 events, 25 endpoints	Growth: \$0.20 per 1,000 events
Higher tier	\$499/mo — 250,000 events, 50 endpoints	Enterprise: custom pricing
Pricing model	Flat monthly	Per-event (usage-based)

The pricing tradeoff: Hookdeck's free tier is more generous (100k vs 5k events). But once you're paying, EventDock's flat pricing is more predictable. At 50,000 events/month, Hookdeck's Growth plan costs roughly \$10/month — cheaper than EventDock's \$149. But EventDock includes a fixed feature set with no per-event overages, and the cost stays flat even if you get a burst of retries or replays.

For teams that value cost predictability over raw per-event pricing, EventDock's model is simpler to budget for.

Quick Start: EventDock in 2 Minutes

# 1. Sign up at dashboard.eventdock.app (free, no credit card)

  
  
  2. Create an endpoint — you get a URL like:


https://in.eventdock.app/ep_abc123

  
  
  3. Set your destination (where webhooks should be delivered):


https://api.yourapp.com/webhooks/stripe

  
  
  4. Point Stripe (or any provider) at your EventDock URL:


  
  
  Stripe Dashboard → Webhooks → Add endpoint


  
  
  URL: https://in.eventdock.app/ep_abc123


  
  
  That's it. EventDock handles retries, DLQ, and monitoring.

When NOT to Use EventDock

Honesty builds trust, so here's when EventDock is not the right choice:

You need payload transformations. If you need to rewrite webhook payloads before they reach your server (e.g., converting between data formats), Hookdeck's transformation feature is genuinely useful. EventDock delivers payloads as-is.
You need complex routing. If a single webhook source needs to fan out to 5 different services with different filtering rules, Hookdeck's Connections model is designed for that. EventDock is one-to-one: one endpoint, one destination.
You process 100k+ events/month and want the cheapest per-event price. Hookdeck's usage-based pricing can be cheaper at scale if you don't value flat pricing.
You're building an event mesh or complex event-driven architecture. Hookdeck is positioned more as event infrastructure. EventDock is positioned as a reliability layer.

The Bottom Line

Choose Hookdeck if you need webhook orchestration — transformations, routing, filtering, and enterprise-grade event infrastructure.

Choose EventDock if you need straightforward webhook reliability — retries, DLQ, monitoring, and signature verification — with simple setup, edge-native performance, and predictable pricing.

Both are solid products. The right choice depends on whether you need a webhook platform or a webhook reliability layer.

Try EventDock Free

5,000 events/month, 3 endpoints, no credit card required. Set up in 2 minutes.

Start Free

The Webhook Security Checklist to Run Before You Go Live

EventDock — Tue, 14 Jul 2026 08:39:04 +0000

Most webhook security bugs are not exotic. They are the same handful of mistakes, shipped by teams who verified a signature once, saw it pass, and moved on. This is the checklist to run before a webhook endpoint goes to production. Each item is something an attacker or a bad network day will find if you skip it, and every one of them has burned a real integration.

1. Verify the signature against the raw body

This is the single most common webhook bug across every provider. The signature is an HMAC computed over the exact bytes the provider sent. If your framework parses the JSON and you rebuild a string from the parsed object to check against, the bytes are no longer identical. Key order shifts, whitespace collapses, numbers get reformatted, and a perfectly correct HMAC never matches.

Capture the raw, unparsed body, verify against it, and parse only after the check passes. The mechanics differ per framework: Express needs express.raw(), Next.js route handlers use await req.text(), Cloudflare Workers use await request.text(). The rule holds for Stripe, Paddle, HubSpot, and Slack alike. If you want the per-provider details side by side, see the webhook signature verification comparison.

2. Compare signatures in constant time

Once you have computed the expected signature, do not compare it with === or ==. A normal string comparison returns as soon as it hits the first differing character, and the tiny timing difference leaks how many leading bytes were correct. Given enough attempts, that is enough to forge a valid signature one byte at a time.

Use a constant-time comparison: crypto.timingSafeEqual in Node, hmac.compare_digest in Python, hash_equals in PHP. They take the same amount of time whether the first byte differs or the last one does. Make sure both buffers are the same length first, because timingSafeEqual throws on a length mismatch.

3. Enforce a timestamp and a replay window

A valid signature proves the request came from the provider. It does not prove the request is fresh. If an attacker captures one signed request, nothing stops them from replaying it a thousand times unless you check the timestamp.

Most providers fold a timestamp into the signed string exactly so you can reject stale requests. Stripe, HubSpot, and Slack all sign a timestamp and recommend rejecting anything older than five minutes. Read the timestamp, confirm it is within your tolerance of now, and reject it if it is not. This is also why you sign the timestamp plus the body rather than the body alone. Twilio is the exception here: it signs the request URL rather than a timestamp, so its replay story is different and worth understanding on its own in the Twilio validation guide.

4. Fail closed, and log what failed

When verification fails, return a 401 or 403 and drop the request. Do not process it "just in case." And do not fall back to processing unsigned requests because signature checking was "acting up" in staging. A webhook endpoint that accepts unsigned requests is an open door with a lock bolted to the wall next to it.

Log enough to debug a real failure without leaking secrets: the header that arrived, the timestamp, and whether the failure was a bad signature versus a stale timestamp versus a missing header. Never log the signing secret or the computed HMAC. When a provider rotates a secret or a proxy mangles a header, these logs are the difference between a five-minute fix and an afternoon.

5. Handle signing secrets like the credentials they are

One secret per endpoint. Stripe issues a distinct whsec_ per endpoint. Using the wrong one is a silent, total verification failure. Map each endpoint to its own secret.
Out of source, in the environment. Signing secrets belong in your secret manager or environment, not committed to the repo. A leaked signing secret lets anyone forge requests you will happily trust.
Rotatable. Build for rotation before you need it. Support two valid secrets at once for a short window so you can roll a secret without dropping live traffic, then retire the old one.

6. Make your handler idempotent

Providers retry. A delivery that times out, or one where your app returns a 500, will be sent again, and sometimes a provider sends the same event twice even on success. If your handler charges a card, sends an email, or increments a counter without checking whether it already processed that event, retries turn into duplicate side effects.

Every provider gives you a stable event ID. Record the IDs you have processed and make the second delivery of the same ID a no-op. This is the difference between a retry being a safety net and a retry being a second charge. The exactly-once processing pattern covers how to do this without a race.

7. HTTPS only, and validate the payload shape

Serve the webhook endpoint over HTTPS so the signed request is not readable or modifiable in transit. Then treat the verified payload as input you still have to validate. A signature proves the provider sent it. It does not prove the event type is one you handle, that the fields you need are present, or that an amount is within a sane range. Check the event type against an allowlist and validate the fields you read before acting on them.

8. The item a security review usually forgets: the events you never receive

Every item above hardens the requests that arrive. None of them help with the request that never gets to you. The webhook that fired while your server was mid-deploy, the burst that timed out during a traffic spike, the event dropped because your handler threw before it acknowledged. Provider retry behavior is uneven: Stripe and Shopify retry for days, Slack retries a few times and can then disable your endpoint, Twilio barely retries at all. The events tied to money and to state are exactly the ones you can least afford to silently lose, and a signature check does nothing to catch a delivery that never happened.

That is the layer EventDock adds under the same checklist. You point any provider at EventDock instead of your app. EventDock verifies the signature against the raw body, stores the event, and acknowledges the provider immediately so no timeout window matters, then delivers to your app with its own retries and a dead-letter queue you can replay by hand. If your app is down for an hour, the events wait and arrive when it recovers instead of vanishing. Signature verification and delivery reliability are two halves of the same problem, and a webhook is only as secure as it is durable.

You can wire up any provider on the free tier and watch every event get verified, stored, and delivered. Start with EventDock free.

How to Verify Slack Request Signatures (and Not Get Your Endpoint Disabled)

EventDock — Tue, 14 Jul 2026 08:37:59 +0000

Slack signs every request it sends your app with a scheme it calls v0. The verification itself is a few lines, but two details trip people up more than anything else: you have to hash the raw request body (not a re-encoded copy of it), and the timestamp is part of the signed string. Get either wrong and every request looks forged. This post shows the exact v0 verification, the raw-body trap, and why a failed check can quietly get your endpoint disabled.

For how this compares to the other major providers, see webhook signature verification compared across Stripe, Paddle, HubSpot, Slack, and Twilio.

The two headers Slack sends

Every request from Slack carries two headers you need:

X-Slack-Signature: the signature, always prefixed with v0= followed by a hex digest.
X-Slack-Request-Timestamp: a Unix timestamp (seconds) for when Slack sent the request.

The signing secret you verify against is not a bot token. You find it in your app config under Basic Information, and it looks like a 32-character hex string. One signing secret per Slack app.

What Slack actually signs

Slack builds one string and signs it:

v0:{timestamp}:{raw_request_body}

Three parts joined by colons: the literal v0, the value from the X-Slack-Request-Timestamp header, and the exact raw body of the request. It then computes an HMAC-SHA256 of that string using your signing secret as the key, hex-encodes it, and prefixes v0=. That final value is what arrives in X-Slack-Signature.

The part people miss: the timestamp is inside the signed string. If you hash only the body, or only the body plus secret, you will never match Slack. The timestamp being signed is also what lets you reject replays, because an attacker cannot swap in a fresh timestamp without breaking the signature.

The raw-body trap

HMAC signs bytes. Slack computed its digest over the exact bytes it put on the wire. Slash commands arrive as application/x-www-form-urlencoded and event and interaction payloads arrive as JSON, but in both cases you must verify against the untouched body.

Here is how the bytes get changed without you noticing. Your web framework reads the body and parses it into an object for you. You then rebuild a string from that object to pass to your verify function. That rebuilt string is not byte-identical to what Slack sent, because form encoding, key order, and escaping can all shift. The HMAC no longer matches and you reject every real request. Verify against the raw body first, parse it only after the signature passes.

Verifying a v0 signature in Node.js

This reads the two headers, rebuilds the signed string, computes the HMAC, compares in constant time, and rejects anything older than five minutes.

import crypto from 'crypto';

function verifySlackRequest(
  rawBody,          // the exact bytes Slack sent, NOT a re-encoded object
  signatureHeader,  // X-Slack-Signature, e.g. "v0=a2b1c3..."
  timestamp,        // X-Slack-Request-Timestamp
  signingSecret     // from Basic Information -> App Credentials
) {
  // Reject replays. The timestamp is signed, so it cannot be forged fresh.
  const fiveMinutes = 60 * 5;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > fiveMinutes) {
    return false;
  }

  const base = 'v0:' + timestamp + ':' + rawBody;
  const expected = 'v0=' + crypto
    .createHmac('sha256', signingSecret)
    .update(base, 'utf8')
    .digest('hex');

  // Constant-time compare to avoid leaking the digest through timing.
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

There is no JSON.parse or form parser in that function. Parsing happens in your handler, after the check returns true.

Getting the raw body in Express and Next.js

The verify function is the easy part. Handing it the untouched body is where frameworks fight you, because they parse the body by default.

// Express: raw parser on the Slack route so req.body stays a Buffer
app.post('/slack/events',
  express.raw({ type: '*/*' }),   // Slack sends both urlencoded and JSON
  (req, res) => {
    const sig = req.get('X-Slack-Signature');
    const ts = req.get('X-Slack-Request-Timestamp');
    if (!verifySlackRequest(req.body.toString('utf8'), sig, ts, process.env.SLACK_SIGNING_SECRET)) {
      return res.status(401).send('bad signature');
    }
    res.status(200).send('');       // ack within 3 seconds
    handleSlackEvent(req.body.toString('utf8')).catch(console.error);
  }
);

In a Next.js route handler, read the body once with await req.text() and do not call req.json() or req.formData() first, because the stream can only be read once. In Cloudflare Workers, await request.text() gives you the raw bytes and the Web Crypto API does the HMAC.

Why a failed check is worse than a rejected request

Slack expects a 2xx response within 3 seconds. For the Events API, if your endpoint is slow, errors, or rejects a request Slack thinks is valid, Slack retries the delivery up to three times: nearly immediately, then after 1 minute, then after 5 minutes. And if your failure rate climbs past 95 percent of delivery attempts inside a 60-minute window, Slack temporarily disables event delivery to your app, so you stop receiving events entirely until you notice and re-enable it. A bad deploy or a database timeout during a busy window can push you there, and a missed app_mention or interaction is a user action your app silently ignored.

Signature verification protects you from forged requests. It does nothing for the requests you drop because your handler was mid-deploy, or the ones Slack stops sending after it decides your endpoint is unhealthy. That is the gap EventDock fills. You point Slack at EventDock instead of your app. EventDock verifies the request, stores it, and acknowledges Slack right away so the 3-second window is never the thing that fails, then forwards it to your app with its own retries and a dead-letter queue you can replay by hand. If your app is down for an hour, the events wait in the queue and arrive once it recovers.

You can wire it up on the free tier and watch every Slack event get captured and delivered. Start with EventDock free, or read how the exactly-once processing pattern handles the duplicate deliveries that Slack, like every retrying sender, will eventually send you.

How to Validate Twilio Webhook Signatures (and the Proxy Trap That Breaks Them)

EventDock — Tue, 14 Jul 2026 08:36:55 +0000

Twilio's webhook signature is different from most, and it catches people in a specific way: the signature is computed over the full request URL, not just the body. So the moment your app sits behind a load balancer or a proxy that rewrites the scheme or host, the URL your server reconstructs stops matching the URL Twilio signed, and every request fails validation even though nothing is wrong. This post shows the exact scheme, the URL-reconstruction trap, and why losing a Twilio status callback is usually permanent.

For how this compares to the other major providers, see webhook signature verification compared across Stripe, Paddle, HubSpot, Slack, and Twilio.

What Twilio signs

Twilio sends an X-Twilio-Signature header with every request to your webhook. It is built like this:

Start with the full URL Twilio requested, exactly as you configured it, including the scheme, host, path, and any query string.
If the request is a POST with form-encoded parameters, take those POST params, sort them alphabetically by key, and append each one to the URL string as the key immediately followed by its value, with no separators.
Compute an HMAC-SHA1 of that combined string, keyed with your account Auth Token (not an API key).
Base64-encode the result. That is what lands in X-Twilio-Signature.

To validate, you rebuild the same string, compute your own HMAC-SHA1, and compare. The key is the Auth Token from your Twilio Console. Two things about this scheme surprise people: the URL is part of the signed material, and the POST parameters get concatenated onto it in sorted order rather than being hashed as a body.

The URL-reconstruction trap

Because the URL is signed, your server has to reconstruct the exact URL Twilio used. That is harder than it sounds in production:

Scheme. You configured an https:// webhook, but your app sits behind a load balancer that terminates TLS and forwards plain http:// internally. Your framework sees http, rebuilds an http:// URL, and the signature no longer matches. Use the X-Forwarded-Proto header to recover the original scheme.
Host and port. A proxy can change the host your app sees. The signed URL used the public host Twilio called, so you have to reconstruct that one, not the internal one.
Query string. If you configured the webhook with query parameters, they are part of the signed URL and must be present, in the same order.

This is the single most common reason Twilio validation fails in production and passes on localhost. On localhost there is no proxy, so the reconstructed URL matches. Ship it behind a load balancer and it breaks.

Validating in Node.js

Twilio ships an official validator in its SDK, and you should use it rather than hand-rolling the HMAC. The important part is feeding it the correct URL and the raw POST params.

import twilio from 'twilio';

app.post('/webhooks/twilio',
  express.urlencoded({ extended: false }),   // Twilio posts form-encoded params
  (req, res) => {
    const signature = req.get('X-Twilio-Signature');

    // Rebuild the EXACT public URL Twilio called. Honor the proxy's forwarded proto/host.
    const proto = req.get('X-Forwarded-Proto') || req.protocol;
    const host  = req.get('X-Forwarded-Host')  || req.get('Host');
    const url   = proto + '://' + host + req.originalUrl;

    const valid = twilio.validateRequest(
      process.env.TWILIO_AUTH_TOKEN,   // the signing key
      signature,
      url,
      req.body                         // the parsed POST params, as an object
    );

    if (!valid) return res.status(403).send('bad signature');

    res.type('text/xml').send('<Response/>');   // ack fast
    handleTwilioEvent(req.body).catch(console.error);
  }
);

If you validate by hand instead, the rule is the one above: URL, then each POST param appended as sorted key + value, HMAC-SHA1 with the Auth Token, Base64. A JSON body uses a different mechanism (Twilio adds a bodySHA256 query parameter), so stick to the SDK if you accept JSON.

Trust the right forwarded headers

Reading X-Forwarded-Proto and X-Forwarded-Host only works if a proxy you trust actually sets them. In Express, set app.set('trust proxy', true) so req.protocol reflects the forwarded scheme, and make sure your load balancer is configured to pass the original host through. If you do not control the proxy headers, the safest fix is to hardcode the exact public URL you configured in Twilio and validate against that constant, since you already know what it is.

A dropped Twilio callback is usually gone for good

Signature validation confirms a request really came from Twilio. It does nothing for the callbacks you never receive. A message-status or call-status callback tells you a text was delivered or a call completed, and Twilio's retry behavior for these is limited, so you should not count on a retry to cover a callback you dropped. If your endpoint is mid-deploy or times out when that callback fires, your records can end up saying a message is still "sending" that actually delivered, or you miss a failed delivery you needed to react to.

This is where a reliability layer earns its place. You point Twilio at EventDock instead of your app. EventDock validates the request, stores it, and acknowledges Twilio right away inside the timeout, then forwards it to your app with its own retries and a dead-letter queue you can replay by hand. If your app is down for an hour, the callbacks wait in the queue and arrive once it recovers, instead of vanishing.

You can wire it up on the free tier and watch every Twilio callback get captured and delivered. Start with EventDock free, or read how the exactly-once processing pattern handles the duplicate deliveries that any retrying pipeline will eventually produce.

Webhook Signature Verification Compared: Stripe, Paddle, HubSpot, Slack, Twilio

EventDock — Mon, 13 Jul 2026 13:58:19 +0000

Every webhook provider signs its requests differently, and the differences are exactly the kind that cost you an afternoon. Some sign the raw body, one signs the URL, most fold in a timestamp for replay protection and one does not. This is a side-by-side comparison of how Stripe, Paddle, HubSpot, Slack, and Twilio sign webhooks, what each one gets wrong most often, and the one trap they nearly all share.

The comparison

Provider	Header	Algorithm	What it signs	Encoding	Replay protection
Stripe	Stripe-Signature	HMAC-SHA256	timestamp . payload	hex	Yes (5-min tolerance)
Paddle (Billing)	Paddle-Signature	HMAC-SHA256	ts : rawBody	hex	Yes (timestamp signed)
HubSpot (v3)	X-HubSpot-Signature-v3	HMAC-SHA256	method + uri + body + timestamp	Base64	Yes (5-min)
Slack	X-Slack-Signature	HMAC-SHA256	v0 : timestamp : body	hex (with v0= prefix)	Yes (5-min)
Twilio	X-Twilio-Signature	HMAC-SHA1	full URL + sorted POST params	Base64	No (URL-based)

Two things jump out. Twilio is the odd one: it uses SHA1 instead of SHA256, and it signs the request URL rather than the body, which changes the whole failure mode. And four of the five fold a timestamp into the signed string, which is what lets you reject replayed requests. Twilio does not, so its signature is tied to the URL instead.

The trap almost all of them share: the raw body

For Stripe, Paddle, HubSpot, and Slack, the signature is computed over the exact bytes of the request body. HMAC signs bytes, not objects. If your web framework parses the JSON and you rebuild a string from the parsed object to verify against, those bytes are not identical to what the provider sent. Key order shifts, whitespace disappears, numbers get reformatted, and your signature never matches. Every one of these four breaks the same way if you verify against a re-serialized body instead of the raw one.

The fix is always the same: capture the raw, unparsed body, verify the signature against it, and only parse it after the check passes. The mechanics of getting the raw body differ per framework (Express needs express.raw(), Next.js route handlers use await req.text(), Cloudflare Workers use await request.text()), but the rule holds across all four providers.

What each one gets wrong most often

Stripe signs {timestamp}.{payload} with your endpoint's signing secret (the whsec_ value, one per endpoint). The common miss is using the wrong endpoint's secret, or verifying against a re-serialized body. Deep dive on Stripe webhook failures.
Paddle Billing signs ts:rawBody, not the body alone. Miss the ts: prefix and every signature is wrong even with correct HMAC code. Also, Paddle Classic uses a completely different RSA scheme, so first confirm which product you are on. Paddle signature guide.
HubSpot has three signature versions with similar header names. Use v3, and note it signs the full URL (normalized) plus the body plus the timestamp, and it is Base64 not hex. HubSpot v1/v2/v3 guide.
Slack signs v0:{timestamp}:{body} with your signing secret and prefixes the result with v0=. A failed check can eventually get Slack to disable event delivery to your app, so it is worth getting right. Slack v0 guide.
Twilio signs the full request URL, so the classic failure is a proxy or load balancer rewriting the scheme or host, making your reconstructed URL differ from the one Twilio signed. Recover the original with X-Forwarded-Proto and the public host. Twilio validation guide.

Signatures are the easy half

Every scheme above answers the same question: is this request really from the provider? None of them answer the harder one: what about the webhooks you never receive? A verified signature does nothing for the event that arrived while your server was mid-deploy, or the burst that timed out during a traffic spike. Stripe and Shopify retry for days, Slack retries a few times then can disable your endpoint, and Twilio barely retries at all. The behavior you can rely on is uneven, so the events that matter, the ones tied to money and to state, are the ones you can least afford to drop.

That is the layer EventDock adds. You point any of these providers at EventDock instead of your app. EventDock verifies the signature, stores the event, acknowledges the provider immediately so no timeout window matters, then delivers to your app with its own retries and a dead-letter queue you can replay by hand. One reliability layer, the same behavior across every provider, whether the provider itself retries generously or not at all.

You can wire up any provider on the free tier and watch every event get captured and delivered. Start with EventDock free.

How to Verify HubSpot Webhook Signatures (v1, v2, and the v3 You Should Actually Use)

EventDock — Wed, 08 Jul 2026 11:14:13 +0000

HubSpot has shipped three different webhook signature schemes over the years, and they all use similar header names. Most of the broken HubSpot webhook validation I have seen comes from implementing v1 when HubSpot is sending v3, or hashing the wrong string. This post shows the three versions, the exact v3 verification HubSpot recommends today, and the raw-body and URL mistakes that make every request look invalid.

If you just want the short version: use v3, hash the method plus the full URI plus the raw body plus the timestamp, and reject anything older than five minutes.

Three signature versions, and which one you are getting

HubSpot did not replace its old signatures when it added new ones. An app can receive any of them depending on how the webhook was configured and how old the app is. The three schemes are not interchangeable, so the first job is knowing which one HubSpot is sending you.

v1 (X-HubSpot-Signature, no version header): a SHA-256 hash of your app client secret concatenated with the raw request body. No timestamp, so no replay protection. This is the oldest and weakest scheme.
v2 (X-HubSpot-Signature with X-HubSpot-Signature-Version: v2): a SHA-256 hash of the client secret plus the HTTP method plus the full URI plus the raw body. Still no timestamp.
v3 (X-HubSpot-Signature-v3 plus X-HubSpot-Request-Timestamp): an HMAC-SHA256, keyed with the client secret, over the HTTP method plus the URI plus the raw body plus the timestamp, then Base64 encoded. The timestamp is signed, which is what gives you replay protection. This is the one HubSpot recommends now.

Look at the headers on an actual delivery. If you see X-HubSpot-Signature-v3, you are on v3 and everything below applies. If you only see X-HubSpot-Signature, check the version header to tell v1 from v2.

What v3 actually signs

The v3 signature is computed over one concatenated string, in this exact order:

HTTP_METHOD + FULL_URI + RAW_REQUEST_BODY + TIMESTAMP

Four things people get wrong here, in order of how often I see them:

The raw body. HMAC signs bytes. If your framework parsed the JSON and you re-serialized it with JSON.stringify, the bytes changed and the signature will never match. Verify against the untouched body.
The full URI, normalized. This means the complete URL HubSpot called, including the https:// scheme, the host, the path, and any query string. Two extra rules for v3 that bite people: HubSpot URL-decodes a specific set of characters in the URI before signing, and it drops any fragment. So the string you sign is the normalized URI, not the raw one off the wire. Match HubSpot's normalization or the hash will differ.
The timestamp. It comes from the X-HubSpot-Request-Timestamp header and it is part of the signed string. Leave it out and every signature is wrong.
Base64, not hex. v3 is Base64 encoded. v1 and v2 are hex. If you compare a hex digest to the Base64 header, it fails even when everything else is right.

Verifying a v3 signature in Node.js

This reads the two headers, rebuilds the signed string, computes the HMAC, compares in constant time, and rejects stale timestamps to block replays.

import crypto from 'crypto';

function verifyHubSpotV3(
  method,           // 'POST'
  fullUri,          // 'https://your-app.com/webhooks/hubspot?x=1'  (exactly what HubSpot called)
  rawBody,          // the untouched request body as a string, NOT re-stringified JSON
  signatureHeader,  // X-HubSpot-Signature-v3
  timestamp,        // X-HubSpot-Request-Timestamp
  clientSecret      // your app's client secret
) {
  // Reject replays: the timestamp is signed, so it cannot be forged past this window.
  const FIVE_MIN = 5 * 60 * 1000;
  if (Date.now() - Number(timestamp) > FIVE_MIN) return false;

  const signedString = method + fullUri + rawBody + timestamp;
  const expected = crypto
    .createHmac('sha256', clientSecret)
    .update(signedString, 'utf8')
    .digest('base64');

  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Notice there is no JSON.parse in that function. Parse the body only after the signature passes.

Getting the raw body (the part frameworks fight you on)

The verification is easy. Handing it the exact bytes HubSpot sent is where most setups break, because web frameworks parse the body for you by default.

// Express: use the raw parser on the webhook route so req.body stays a Buffer
app.post('/webhooks/hubspot',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.get('X-HubSpot-Signature-v3');
    const ts = req.get('X-HubSpot-Request-Timestamp');
    const fullUri = 'https://your-app.com' + req.originalUrl; // include the query string
    if (!verifyHubSpotV3('POST', fullUri, req.body.toString('utf8'), sig, ts, process.env.HUBSPOT_CLIENT_SECRET)) {
      return res.status(401).send('bad signature');
    }
    res.status(200).send('ok');          // ack fast
    handleHubSpotEvent(JSON.parse(req.body.toString('utf8'))).catch(console.error);
  }
);

In Next.js route handlers, read the body once with await req.text() and do not call req.json() first, because you cannot read the stream twice. In Cloudflare Workers, await request.text() gives you the raw bytes and the Web Crypto API does the HMAC.

Signatures prove authenticity. They do nothing for lost events.

HubSpot batches webhook events and retries failed deliveries for up to a few days, then gives up. That window feels safe until a deploy, a database timeout, or a cold start eats a burst of contact.propertyChange or deal.creation events during the minutes your handler is down. A missed deal.creation is a lead your CRM automation never fired on. A missed contact.deletion is a record you keep syncing after the customer asked to be forgotten.

This is where EventDock fits. You point HubSpot at EventDock instead of directly at your app. EventDock verifies the signature, stores the event, acknowledges HubSpot right away so the delivery is safely captured, then forwards it to your app with its own retries and a dead-letter queue you can replay by hand. If your app is down for an hour, the events wait in the queue and arrive once it recovers.

You can wire it up on the free tier and watch every HubSpot event get captured and delivered. Start with EventDock free, or read how the exactly-once processing pattern handles the duplicate deliveries that HubSpot, like every retrying provider, will eventually send you.

How to Verify Paddle Billing Webhook Signatures (and the Raw-Body Bug That Breaks Them)

EventDock — Mon, 06 Jul 2026 14:39:49 +0000

Most Paddle webhook signature failures come down to one thing: you verified the signature against the wrong bytes. Your framework parsed the JSON, you re-serialized it, and the HMAC no longer matches what Paddle signed. The event looks tampered with even though nothing is wrong. This post shows the exact verification Paddle Billing expects, the raw-body trap that breaks it, and the difference between Paddle Billing and the older Paddle Classic scheme that sends people down the wrong path.

EventDock's own billing runs on Paddle Billing, so the code below is the same shape we use in production.

First: are you on Paddle Billing or Paddle Classic?

Paddle has two products with two completely different webhook signature schemes, and a lot of the older blog posts and Stack Overflow answers describe the wrong one.

Paddle Classic (the original product) sends a p_signature field inside the form-encoded body. It requires PHP serialization and is verified with Paddle's public key.
Paddle Billing (the current product) sends a Paddle-Signature HTTP header. It is an HMAC-SHA256 over the raw request body, keyed with a per-notification-destination secret. No public key needed.

If your webhook secret looks like pdl_ntfset_... and you see a Paddle-Signature header, you are on Paddle Billing. Accounts created after August 2023 are on Paddle Billing by default, and Classic is legacy. Everything below is for Paddle Billing.

What the Paddle-Signature header actually contains

Every Paddle Billing webhook arrives with a header like this:

Paddle-Signature: ts=1717000000;h1=eb4d0a2f...<64 hex chars>

Two fields, separated by a semicolon:

ts is a Unix timestamp (seconds) for when Paddle sent the request.
h1 is the HMAC-SHA256 digest, in lowercase hex.

The detail that the field names hide: Paddle does not sign the body on its own. It signs the string {ts}:{raw_body}. The timestamp is part of the signed material, which is what lets you reject replayed requests. Miss the ts: prefix and every signature you compute will be wrong even though your HMAC code is correct.

The raw-body trap

HMAC signs bytes, not objects. Paddle computed its digest over the exact bytes it put on the wire. If you hand your verification function anything other than those exact bytes, the digest will not match.

Here is how the bytes get changed without you noticing:

Your web framework reads the request body and parses it into a JSON object for you.
You call your verify function and pass it JSON.stringify(req.body) to turn the object back into a string.
That re-serialized string is not byte-identical to what Paddle sent. Key order can change, whitespace disappears, unicode escapes differ, floating-point numbers get reformatted.
Your HMAC is computed over different bytes, so h1 never matches, and you reject every real webhook as invalid.

The fix is always the same: verify against the raw, unparsed request body, then parse it only after the signature passes. Every framework has its own way to get the raw body, and getting it wrong is the most common cause of Paddle verification failures.

A correct verification in Node.js

It reads the two header fields, rebuilds the signed string as ts:body, computes the HMAC, compares in constant time, and rejects requests whose timestamp is too old to be fresh.

import crypto from 'crypto';

function verifyPaddleSignature(
  rawBody: string,       // the exact bytes Paddle sent, NOT a re-stringified object
  signatureHeader: string,
  secret: string         // your notification destination secret, pdl_ntfset_...
): boolean {
  // Header looks like: ts=1717000000;h1=abc123...
  let ts = '';
  let h1 = '';
  for (const part of signatureHeader.split(';')) {
    const [key, value] = part.split('=');
    if (key === 'ts') ts = value;
    if (key === 'h1') h1 = value;
  }
  if (!ts || !h1) return false;

  // Reject replays: the timestamp is signed, so an attacker cannot forge a fresh one.
  // Paddle's own examples use a tight 5-second window. Widen it a little if your
  // servers see clock skew, but keep it short.
  const age = Math.floor(Date.now() / 1000) - Number(ts);
  if (age > 5) return false;

  // Paddle signs the string `${ts}:${rawBody}`, not the body alone.
  const signedPayload = `${ts}:${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Constant-time compare to avoid leaking the digest through timing.
  const a = Buffer.from(h1);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Notice there is no JSON.parse anywhere in that function. Parsing happens after it returns true, in your handler, never before.

Getting the raw body in Express, Next.js, and Cloudflare Workers

The verify function is the simple part. Feeding it the untouched body is where frameworks fight you.

Express

The default express.json() middleware consumes the stream and leaves you only the parsed object. Use the raw parser on the webhook route so you keep the bytes:

app.post('/webhooks/paddle',
  express.raw({ type: 'application/json' }),   // req.body is now a Buffer
  (req, res) => {
    const sig = req.get('Paddle-Signature') ?? '';
    if (!verifyPaddleSignature(req.body.toString('utf8'), sig, process.env.PADDLE_WEBHOOK_SECRET)) {
      return res.status(400).send('bad signature');
    }
    const event = JSON.parse(req.body.toString('utf8'));
    res.status(200).send('ok');   // ack fast, process after
    handlePaddleEvent(event).catch(console.error);
  }
);

Next.js (App Router)

Route handlers give you the raw body directly through await req.text(). Do not call req.json() first, because you cannot read the body twice.

export async function POST(req: Request) {
  const raw = await req.text();               // exact bytes
  const sig = req.headers.get('paddle-signature') ?? '';
  if (!verifyPaddleSignature(raw, sig, process.env.PADDLE_WEBHOOK_SECRET!)) {
    return new Response('bad signature', { status: 400 });
  }
  const event = JSON.parse(raw);
  return Response.json({ ok: true });
}

Cloudflare Workers

Workers give you the raw text with await request.text() and ship the Web Crypto API, so you do not even need the Node crypto module. This is close to what EventDock runs.

const raw = await request.text();
const sig = request.headers.get('paddle-signature') ?? '';
// verify with crypto.subtle.importKey + crypto.subtle.sign('HMAC', ...)
// compare the hex digest to h1

A checklist when it still fails

If you did all that and Paddle webhooks still read as invalid, walk this list in order:

Are you signing ts:body and not just body? This is the second most common miss after the raw body.
Is the secret the right one? Paddle Billing gives each notification destination its own secret. If you have a sandbox destination and a production destination, they have different secrets. A sandbox secret against production traffic fails silently.
Sandbox versus production. Sandbox events come from your sandbox destination and must be checked with the sandbox secret. Do not share one secret across both.
Is a proxy rewriting the body? Some API gateways and body-logging middleware re-encode JSON before it reaches your handler. Check the bytes at the very edge.
Is h1 compared as lowercase hex? Paddle sends lowercase. If you uppercase or Base64 anywhere, the compare fails.

Verification is step one. Delivery is the real problem.

Signature verification tells you a webhook is authentic. It does nothing for the webhooks that never reach you, or the ones you drop because your handler was mid-deploy when Paddle called.

Paddle Billing retries a failed webhook with backoff over about three days, then stops. That window sounds forgiving until a bad deploy, a database timeout, or a cold start eats a burst of subscription.activated and transaction.completed events during the minutes a customer is actually paying you. Lose one and you get a paying customer stuck on a free-tier account, or a churned customer your system still thinks is active.

This is the problem EventDock solves. You point Paddle at EventDock instead of directly at your app. EventDock verifies the signature, stores the event, and acknowledges Paddle right away so the delivery is safely captured before the retry window matters, then forwards it to your app with its own retries and a dead-letter queue you can replay by hand. If your app is down for an hour, the events wait in the queue and arrive once it recovers.

You can wire it up with the free tier and watch every Paddle event get captured and delivered. Start with EventDock free, or read how the exactly-once processing pattern handles the duplicate deliveries that every retrying provider, Paddle included, will eventually send you.

Fix "Required headers missing: x-hub-signature-256" in @octokit/webhooks

EventDock — Fri, 03 Jul 2026 13:17:40 +0000

This guide also lives on eventdock.app.

Your GitHub webhook handler responds 400 with:

{"error": "Required headers missing: x-hub-signature-256"}

(older @octokit/webhooks versions: x-hub-signature)

The middleware checks three headers on every delivery — x-github-event, x-hub-signature-256, x-github-delivery — and rejects the request if any is absent. Here are the causes, ordered by how often they're the culprit.

1. No webhook secret configured (the usual one)

GitHub only signs deliveries when the webhook has a secret. No secret → GitHub omits X-Hub-Signature and X-Hub-Signature-256 entirely → octokit reports them missing.

Fix:

Repo (or org) → Settings → Webhooks → your hook → Secret: set a strong random value.
Pass the same value to your handler:

import { Webhooks, createNodeMiddleware } from "@octokit/webhooks";

const webhooks = new Webhooks({
  secret: process.env.GITHUB_WEBHOOK_SECRET, // must match the webhook's Secret field
});

After setting the secret, use Redeliver on a recent delivery (webhook settings → Recent Deliveries) and confirm the request headers now include X-Hub-Signature-256.

2. The request isn't from GitHub

Health checks, uptime probes, security scanners, and your own curl tests hit the same route without GitHub's headers and trip the 400. Real GitHub deliveries have a User-Agent starting with GitHub-Hookshot/ and a unique X-GitHub-Delivery id. To test locally, copy a payload from Recent Deliveries including all four headers, or just use Redeliver.

3. A proxy or framework strips the headers

Some reverse proxies, API gateways, and serverless adapters drop or rename non-standard X- headers. Diagnose by logging exactly what arrives:

app.use("/api/webhooks", (req, _res, next) => {
  console.log(JSON.stringify(req.headers, null, 2)); // is x-hub-signature-256 present at all?
  next();
});

If the header reaches your edge but not your handler, the thing in between (nginx underscores_in_headers rules, an API gateway header allowlist, a Lambda adapter) is eating it.

4. Old @octokit/webhooks expecting the legacy header

Very old versions (v5-era) validated the SHA-1 x-hub-signature header; current versions require the SHA-256 variant. GitHub sends both when a secret is set, so the practical fix is the same: set the secret, then upgrade @octokit/webhooks.

5. Wrong route wired to the middleware

If createNodeMiddleware(webhooks, { path: "/api/webhooks" }) is mounted on a path that also serves other traffic (or a catch-all), every non-webhook request to it produces this 400 in your logs. Give the webhook endpoint its own dedicated path.

Debugging webhook headers blind? EventDock sits in front of your handler, captures every GitHub delivery with its full original headers, verifies signatures, and retries when your server is down. Free tier: 5,000 events/mo, no card.

What is the worst production bug you have hit on Cloudflare Workers?

EventDock — Tue, 31 Mar 2026 17:02:41 +0000

I recently shipped a webhook relay service on Cloudflare Workers and hit some genuinely painful production bugs — the kind where everything looks fine but data is silently disappearing.

The worst one: an async function that was not awaited in a queue consumer. In Node.js, the fire-and-forget promise would probably complete. On Cloudflare Workers, the runtime kills the execution context once the handler returns, so the promise just... vanishes. Events that needed retries silently stopped existing.

Another fun one: a cron-based recovery system that was supposed to catch exactly these failures — except the cron trigger in wrangler.toml was commented out. The safety net did not exist for months.

I wrote up all four bugs in detail here: I Built a Webhook Relay on Cloudflare Workers. Here Are the Bugs That Killed It

What is the worst production bug you have hit on Cloudflare Workers (or any edge/serverless platform)? The "distributed systems fail in ways that look like success" category especially — where metrics look fine but data is quietly being lost.