DEV Community: Webhooker

Your Stripe handler is shipping orders nobody paid for

Webhooker — Fri, 09 Oct 2026 19:55:14 +0000

Here is the Stripe Checkout handler most of us wrote first:

if (event.type === "checkout.session.completed") {
  await fulfilOrder(event.data.object);
}

It passes every test with 4242 4242 4242 4242. It goes live, cards work, everyone moves on.

Then someone in Germany pays with SEPA Direct Debit. The order ships the same minute. Four days later the debit bounces, and you have sent a parcel to someone who never paid for it.

Nothing in that handler is wrong for cards. It just reads the event name as "payment succeeded", and the event does not say that.

completed means the customer finished, not that you got paid

checkout.session.completed fires when the customer submits the Checkout page. Stripe's own description of the session's status: "complete" is careful about this: "The checkout session is complete. Payment processing may still be in progress."

Whether you actually have the money lives in a different field, payment_status:

paid: the funds are in your account
unpaid: the funds are not there yet
no_payment_required: nothing to collect, like a free trial or a 100% coupon

With cards, iDEAL or Bancontact the session completes as paid, so the bug stays invisible. With SEPA Direct Debit, Bacs Direct Debit or a bank transfer, Checkout completes before the bank has said anything, and the session arrives as unpaid. The real outcome shows up days later:

day 0     checkout.session.completed                payment_status: "unpaid"
day 0     payment_intent.processing
day 2-5   payment_intent.succeeded                  (or payment_failed)
day 2-5   checkout.session.async_payment_succeeded  payment_status: "paid"
          (or checkout.session.async_payment_failed)

If you sell in Europe, this is not an edge case. SEPA is a very normal way to pay here.

The obvious fix makes it worse

The first instinct is to switch to payment_intent.succeeded, since that one only fires once the money is confirmed. It does fix SEPA. It also breaks three other things.

Free orders stop working. No money moved, so there is no successful PaymentIntent and the event never fires. The giveaway, the free tier and the 100% launch coupon all complete Checkout and then sit there. Those are exactly the orders nobody looks at until a customer complains.

Subscriptions fulfil twice, then forever. Every paid invoice produces its own payment_intent.succeeded. Your handler cannot tell a new subscriber from their twelfth renewal without extra lookups, and if you kept the session handler too, month one gets processed twice.

The payload has nothing you need. A PaymentIntent knows the amount and currency. It does not know the line items, the address the customer typed into Checkout, your client_reference_id, or the metadata you set on the session. Session metadata is not copied over unless you also pass it as payment_intent_data.metadata. Most handlers built this way end up calling the API to find the Checkout Session again, which is a long way round to the event they started with.

And one more: payment_intent.succeeded is account-wide. If another app on the same Stripe account takes payments, or Billing charges an invoice, your Checkout handler gets those events too.

The rule that covers every case

For Checkout and Payment Links:

Listen to checkout.session.completed and checkout.session.async_payment_succeeded.
Send both into the same fulfilment function.
Fulfil only when payment_status is not unpaid.

The third rule is what makes it work. Card orders pass on the first event. SEPA orders get skipped on the first event and pass on the second. Free orders pass as no_payment_required. Subscriptions fulfil once from Checkout, and renewals go through invoice.paid, where they belong.

Handle checkout.session.async_payment_failed too. That is the moment to cancel the order and email the customer, because nobody else is going to tell them their debit failed.

payment_intent.succeeded is still the right event in one setup: when you build your own form with the Payment Element and create PaymentIntents yourself. There is no Checkout Session there, you put the order ID in the intent's metadata, and you fulfil on payment_intent.succeeded. What you should not do is listen to both for the same order. They describe one payment from two objects, and a handler that reacts to both ships twice.

A handler that fulfils exactly once

Stripe delivers at least once and does not promise any order. async_payment_succeeded can land while you are still processing completed, a retry can bring the same event twice, and the customer's browser can hit your success page while the webhook is still in flight. Here is a version that survives all three:

import express from "express";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

const fulfilmentEvents = new Set([
  "checkout.session.completed",
  "checkout.session.async_payment_succeeded",
]);

app.post(
  "/webhooks/stripe",
  express.raw({ type: "application/json" }),
  async (request, response) => {
    let event;
    try {
      event = stripe.webhooks.constructEvent(
        request.body,
        request.headers["stripe-signature"],
        process.env.STRIPE_WEBHOOK_SECRET,
      );
    } catch {
      return response.sendStatus(400);
    }

    if (fulfilmentEvents.has(event.type)) {
      await queue.add("fulfil-checkout", { sessionId: event.data.object.id });
    } else if (event.type === "checkout.session.async_payment_failed") {
      await queue.add("payment-failed", { sessionId: event.data.object.id });
    }

    response.sendStatus(200);
  },
);

// Called by the queue worker and by the success page.
async function fulfilCheckout(sessionId) {
  const session = await stripe.checkout.sessions.retrieve(sessionId, {
    expand: ["line_items"],
  });
  if (session.payment_status === "unpaid") return;

  const claimed = await database.query(
    `INSERT INTO fulfilments (checkout_session_id) VALUES ($1)
     ON CONFLICT (checkout_session_id) DO NOTHING
     RETURNING checkout_session_id`,
    [sessionId],
  );
  if (claimed.rowCount === 0) return;

  await shipLineItems(session.line_items.data, session.customer_details);
}

What each piece is there for:

express.raw keeps the exact bytes Stripe signed. Parse the JSON first and you get No signatures found matching the expected signature.
Enqueue, then answer. When you set a success_url, Checkout waits up to 10 seconds for your endpoint to answer before redirecting the customer. A queue write takes milliseconds. Emails and warehouse calls happen in the worker. Enqueue before the 200, though: answer first, fail to enqueue, and Stripe thinks the event was delivered and never retries.
Retrieve the session fresh. The object in the event is a snapshot from when the event was created. Asking the API for the current state means it no longer matters which of the two events arrives first.
A unique constraint, not a check. Two concurrent calls both pass a SELECT ... WHERE fulfilled. Only one of them wins the INSERT ... ON CONFLICT DO NOTHING.
The success page calls the same function. Put {CHECKOUT_SESSION_ID} in your success_url and call fulfilCheckout when the customer lands. Webhooks can be late, and the unique row makes the second call a no-op.

One caveat on that claim row: if the worker dies after the insert and before shipping, the row says "done" and every retry skips it. If your shipping step is not quick and safe to repeat, record a status on the row and only mark it fulfilled after the work commits.

Testing the path your test cards skip

stripe trigger checkout.session.completed sends a card-shaped event, so it never exercises the delayed path. To see it for real, enable SEPA Direct Debit in your sandbox, go through an actual Checkout, and pay with Stripe's test IBAN AT611904300234573201. You should see checkout.session.completed with payment_status: "unpaid", then checkout.session.async_payment_succeeded shortly after.

If your handler ships on the first one, you have the bug from the top of this post.

Cheat sheet

Your setup	Fulfil on	Also handle
Checkout, cards only	`checkout.session.completed` + `payment_status` check	`checkout.session.expired`
Checkout with SEPA, Bacs or bank transfer	`completed` + `async_payment_succeeded`	`async_payment_failed`
Checkout in subscription mode	`checkout.session.completed` to provision	`invoice.paid`, `invoice.payment_failed`
Your own PaymentIntents (Payment Element)	`payment_intent.succeeded`	`payment_intent.payment_failed`

The full version, with the field-by-field comparison of both events, the subscription event map and why payment_intent is null on a fresh session, is on our blog: checkout.session.completed vs payment_intent.succeeded.

Stop guessing why your webhook signature check fails

Webhooker — Thu, 24 Sep 2026 08:47:12 +0000

No signatures found matching the expected signature for payload.

That is Stripe's wording. GitHub gives you a mismatch on X-Hub-Signature-256, Shopify words it differently again, and hand written handlers usually log something like "invalid signature". They all mean exactly one thing: the HMAC you computed is not the HMAC that arrived.

What none of them tell you is which input was wrong. And that is the whole problem, because there are only four:

the signing secret
the exact bytes of the request body
the hash algorithm
the encoding of the result

Every failed verification is one of those four being different from what the sender used. Four candidates is a small enough space that you should never be guessing. Yet the usual debugging session is an hour of swapping secrets and re-reading docs, because the error message collapses four distinct failures into one string.

Here is how to find the broken input in about five minutes.

First, log the two things that actually narrow it down

Before changing any code, add this to the handler and send one delivery through it:

const raw = await getRawBody(req);   // whatever your framework gives you

console.log({
  bytes: raw.length,
  contentLength: req.headers["content-length"],
  sha256: crypto.createHash("sha256").update(raw).digest("hex").slice(0, 16),
  header: req.headers["stripe-signature"],  // or x-hub-signature-256, etc
});

Never log the raw body itself. It has customer data in it, and now your logging provider has it too. The hash and the length tell you what you need without keeping the payload around.

Two numbers, one comparison, and you have already split the problem in half.

Check one: does the byte count match?

Compare bytes against the content-length header the sender set.

Different? Your body was modified before you hashed it, and nothing else matters until you fix that. This is the single most common cause by a wide margin, and every vendor doc that ranks for this error says so.

The usual culprit is a JSON parser that ran first. express.json(), body-parser, FastAPI's automatic model binding, a framework middleware you never registered explicitly. The parse gives you an object, you re-serialise it to hash it, and JSON.stringify does not reproduce the sender's bytes. Key order can shift. Whitespace is gone. Unicode escaping differs. One byte off and the HMAC is completely different, which is the entire point of a hash.

In Express the fix is to keep the raw buffer on the webhook route only:

app.post("/webhooks/stripe",
  express.raw({ type: "application/json" }),
  (req, res) => {
    // req.body is a Buffer here, not an object
  }
);

Order matters. If app.use(express.json()) is registered above this line, it wins and you are back to a parsed body.

Same number? Good, the body is intact. The problem is one of the other three, and you can stop rewriting your middleware stack.

Check two: is it the secret or the encoding?

Now sign a known value and compare against a known answer, taking your app out of the picture entirely:

const mac = crypto.createHmac("sha256", "test_secret")
  .update("hello")
  .digest("hex");

// 8e3c5f1f7dcbf1e6e9a0d0f2b1e3c... whatever your runtime gives
console.log(mac);

Run the same thing in a plain Node REPL, or openssl dgst -sha256 -hmac test_secret. If the two differ, the bug is in how your code builds the HMAC, not in the webhook at all.

Two specific things to look at here.

Encoding. Stripe sends hex. Shopify sends base64. If you compare a hex digest against a base64 header, the lengths alone will never match, and the failure looks identical to a wrong secret. Check the length of what you computed against the length of what arrived. 64 characters is a hex sha256; 44 characters ending in = is base64.

The secret itself. Copying from a dashboard drags in a trailing newline or space more often than anyone admits, and the value is invisible in logs. Print secret.length once. Stripe signing secrets start with whsec_ and the whole string is the secret, prefix included. Do not strip it. And the signing secret is not the API key: sk_live_ will never verify anything, no matter how correct the rest of the code is.

Check three: are you on an edge runtime?

This one is missing from almost every tutorial, because the tutorials predate the platforms.

Cloudflare Workers, Deno Deploy, Vercel Edge, Supabase Edge Functions. None of them have Node's synchronous crypto. Stripe's constructEvent is synchronous and will throw or silently misbehave there. The async variant exists precisely for this:

const event = await stripe.webhooks.constructEventAsync(
  rawBody, signature, secret
);

That single change is what fixes a surprising number of "it worked on Pages, it broke on Workers" threads. The Cloudflare community has a good example from January where a working webhook broke on migration for exactly this reason.

The second edge trap is that a Request body can only be read once. If anything upstream already called await req.json(), your await req.text() returns an empty string, you hash nothing, and the signature never matches. Read the text first, parse from the string you already have:

const raw = await req.text();       // read once
const signature = req.headers.get("stripe-signature");
const event = await stripe.webhooks.constructEventAsync(raw, signature, secret);
const data = JSON.parse(raw);       // parse from the same string, not the request

If you are writing the HMAC yourself on an edge runtime, it is Web Crypto, and all of it is async:

const key = await crypto.subtle.importKey(
  "raw", new TextEncoder().encode(secret),
  { name: "HMAC", hash: "SHA-256" }, false, ["sign"]
);
const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(raw));
const hex = [...new Uint8Array(mac)].map(b => b.toString(16).padStart(2, "0")).join("");

"It works locally but not in production"

If local is fine and production fails, the four inputs are the same in your code, so something in between changed the request or the environment.

A proxy or CDN that buffers and re-emits the body will change the bytes. So will decompressing a gzipped payload and re-encoding it. Nginx with proxy_set_body, an API gateway doing request transformation, a WAF that normalises JSON. Any of these produce the same symptom as a parser.

Or it is simply the wrong secret for the environment. Test and live endpoints have different signing secrets, and a .env that got copied between them fails in a way that looks mysterious but is not.

One more that catches people: a tunnel used in local development. Some tunnels rewrite headers or re-encode the body, which means local passes for the wrong reason and production is where you first meet real bytes.

While you are in there, fix the comparison

Once verification passes, check how you compare the two values. This is not why it fails, but it is where a fixed handler often stays broken in a way nobody notices:

if (computed === received) { }                 // leaks timing information
if (crypto.timingSafeEqual(a, b)) { }          // constant time

timingSafeEqual throws if the two buffers have different lengths, so guard for that first. And check the timestamp too. A valid signature on a request captured an hour ago is still a valid signature, which is why providers include a timestamp in the signed payload and expect you to reject anything outside a few minutes.

The thing worth keeping

Leave the length and hash logging in permanently. Not the body, just bytes, the truncated hash, and the header. It costs nothing, contains no customer data, and the next time this breaks you will know within one delivery whether the bytes changed or the secret did.

That is really the whole trick. The error message describes a symptom shared by four different causes, so stop reading the message and start measuring the inputs.

Longer write up with the full list of causes, the error strings each provider uses, and what to do about clock skew: Webhook signature verification failed: 6 causes and fixes.

The webhook dedupe everyone copies has a hole in it

Webhooker — Fri, 18 Sep 2026 19:49:36 +0000

If you have ever searched for how to stop processing the same webhook twice, you have seen this snippet:

INSERT INTO processed_events (event_key)
VALUES ($1)
ON CONFLICT (event_key) DO NOTHING
RETURNING event_key;

Got a row back, you are the first one here, do the work. Got nothing, somebody already handled it, return 200 and move on. It is correct, it is atomic, and it beats the check-then-insert version that races itself under load.

It also has a hole. Claim the key, start the work, and have the process die before the work commits: the key stays in the table, marked as handled. Every retry after that hits the conflict branch and returns 200. The sender is happy. The event never happened.

I want to walk through that specific failure, because most dedupe tutorials stop one paragraph before it.

Why you are seeing the same event twice at all

Duplicates are not a provider bug you can report. They fall out of how at-least-once delivery works.

Your handler gets an event, commits the write, and then the response back to the sender gets lost, or your reply lands two seconds after the sender's read timeout. From where the sender sits, that delivery failed, so it sends the event again. Stripe retries failed events for up to three days in live mode, and you can resend anything from the dashboard on top of that. GitHub lets you redeliver anything from the last three days out of the UI.

There is no timeout value that closes the window. The duplicate is a normal outcome of a system that would rather send twice than lose one, so the handler has to make repeats harmless.

The snippet, and where it breaks

Here is the whole thing in Python, roughly as it gets copied into production:

claimed = db.execute(
    "INSERT INTO processed_events (event_key, source) "
    "VALUES (%s, %s) ON CONFLICT (event_key) DO NOTHING "
    "RETURNING event_key",
    [event_key, source],
).fetchone()

if not claimed:
    return 200  # already handled

fulfil_order(event)   # the actual work
return 200

Two things commit here, and they commit separately. The claim goes in first. The work goes in second. Anything that kills the process in between leaves you with a key that says "done" and a side effect that never ran: a pod restart mid-deploy, an OOM kill, a connection drop to the downstream API, a SIGTERM your worker does not handle gracefully.

The window is small. It is also hit constantly, because deploys happen during traffic and webhook volume is bursty. And the failure is quiet: no error, no retry, no alert. The event is just gone, and you find out when a customer emails about the thing they paid for.

Worse, the ordering is what makes it quiet. Do the work first and crash before the claim and you get a duplicate, which is loud and recoverable. Claim first and crash before the work and you get a loss, which is neither.

Fix one: make it a single commit

If the side effect is a write to the same database, this is easy. Put the claim and the work in one transaction and stop thinking about it:

with db.transaction():
    claimed = db.execute(
        "INSERT INTO processed_events (event_key, source) "
        "VALUES (%s, %s) ON CONFLICT (event_key) DO NOTHING "
        "RETURNING event_key",
        [event_key, source],
    ).fetchone()

    if not claimed:
        return 200

    fulfil_order(event)   # same transaction, same commit

Now a crash rolls back both. The key is not there, the next retry claims it cleanly, and the work runs exactly once in the sense that matters: one visible effect. ON CONFLICT still does the concurrency half, and the transaction does the crash half.

One thing to watch: the transaction stays open for as long as fulfil_order runs. If that function calls a third party API with a thirty second timeout, you are holding a database connection and a row lock for thirty seconds per event. At low volume nobody notices. At a few hundred events a minute you run out of connections.

Which brings us to the case this pattern cannot cover.

Fix two: claim with a state, when the work leaves the database

Sending an email, charging a card, calling somebody's API. None of that rolls back with your transaction, so a single commit does not exist to hide behind. What you can do is stop pretending the claim is binary. It has three states, not two.

CREATE TABLE processed_events (
    event_key    TEXT PRIMARY KEY,
    source       TEXT        NOT NULL,
    status       TEXT        NOT NULL,   -- 'in_progress' or 'done'
    claimed_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    completed_at TIMESTAMPTZ
);

The claim becomes an upsert that will take the key back off a worker that has clearly died:

INSERT INTO processed_events (event_key, source, status)
VALUES ($1, $2, 'in_progress')
ON CONFLICT (event_key) DO UPDATE
    SET status = 'in_progress', claimed_at = now()
    WHERE processed_events.status = 'in_progress'
      AND processed_events.claimed_at < now() - interval '5 minutes'
RETURNING event_key;

Three outcomes, and you have to handle all three:

A row comes back and you own the event. Do the work, then set status = 'done' and completed_at = now(). That second update is the only thing that tells future retries to skip.

No row comes back and the stored status is done. Somebody finished this already. Return 200.

No row comes back and the stored status is in_progress with a fresh claimed_at. Another worker has it right now. Do not process, and do not return 200 either: return 409 or 503 so the sender retries in a minute. A 200 here is a lie that costs you the event if the other worker dies.

Since RETURNING cannot tell the last two apart, read the row when the claim fails:

if not claimed:
    status = db.execute(
        "SELECT status FROM processed_events WHERE event_key = %s",
        [event_key],
    ).scalar()
    return 200 if status == "done" else 503

Pick the lease window to be longer than your slowest realistic handler and shorter than your patience. Five minutes is a reasonable default when the work is an HTTP call with a thirty second timeout and a couple of retries. Too short and two workers process the same event; too long and a crashed worker parks the event until the lease expires.

Then make the write idempotent anyway

Dedupe tables fail. Somebody truncates one during a migration, a Redis instance without persistence restarts, a key expires earlier than the provider's retry window. So make the write itself survive being run twice, and the dedupe layer becomes an optimisation rather than the only thing standing between you and a double charge.

A unique constraint on the business key does most of it:

ALTER TABLE orders ADD CONSTRAINT uq_orders_event
    UNIQUE (provider_event_id);

A conditional update covers state transitions, so a replayed payment.succeeded on an invoice that is already paid changes nothing:

UPDATE invoices SET status = 'paid'
WHERE id = $1 AND status = 'pending';

Run either one five times and the database looks the same as after one. That is the actual goal. The dedupe table is just a way to avoid the wasted work.

Use a key that survives the retry

All of the above is worthless if the key changes between copies of the same event. Key on the event's identity, never on the moment it arrived.

Source	Key to use
Stripe	`id` on the event object, the `evt_...` value
GitHub	the `X-GitHub-Delivery` header, which stays the same on a manual redelivery
Shopify	the `X-Shopify-Webhook-Id` header
Webhooker	the `X-Webhooker-Event-Id` header, stable across retries and replays

Do not use a timestamp taken at receipt, a UUID your framework generates per request, or the retry count. Each of those makes every retry look brand new, which turns your dedupe table into an expensive log of things you processed twice.

Also: do not key on the object id inside the payload. A single charge produces several distinct events, and keying on ch_... means the second event gets swallowed as a duplicate of the first.

How to actually test this

Two tests, neither of which needs load:

Send the same delivery twice, in sequence, and assert the side effect happened once. That catches the changing-key mistake, which is more common than the race.

Then kill the process between the claim and the commit. Drop a sys.exit(1) inside fulfil_order, replay the event, restart, replay again, and check that the work eventually happens. If your second replay returns 200 without doing anything, you have the hole, and you now know exactly where it is.

Longer version of this, including the Idempotency-Key header that everyone confuses with webhook dedupe and why it points the other way, is on our blog: Idempotency keys for webhook consumers.