Stripe webhook retries, signatures and idempotency

How long does Stripe retry a failed webhook?

What does Stripe count as a failed delivery?

How do I verify a Stripe webhook signature in Node without the SDK?

import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_SECONDS = 300; // Stripe's own libraries default to five minutes

/** true only for a v1 signature over the raw body inside the tolerance window. */
export function verifyStripe(secret, header, rawBody) {
  let timestamp = null;
  const signatures = [];
  for (const item of String(header ?? '').split(',')) {
    const [key, value] = item.trim().split('=', 2);
    if (key === 't') timestamp = Number(value);
    if (key === 'v1' && value) signatures.push(value); // v0 and unknown schemes are ignored
  }
  if (!Number.isInteger(timestamp) || signatures.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)            // the bytes as received, never a re-serialised object
    .digest('hex');
  const a = Buffer.from(expected, 'hex');
  return signatures.some((sig) => {
    const b = Buffer.from(sig, 'hex');
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

How do I make a Stripe webhook handler idempotent?

import express from 'express';
import { verifyStripe } from './verify-stripe.mjs';

const app = express();

// express.raw, not express.json: the signature is over the bytes Stripe sent.
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifyStripe(process.env.STRIPE_WEBHOOK_SECRET, req.get('stripe-signature'), req.body)) {
    return res.status(400).send('signature verification failed');
  }
  const event = JSON.parse(req.body);

  // CREATE TABLE stripe_events (
  //   id text PRIMARY KEY, type text NOT NULL, payload jsonb NOT NULL,
  //   received_at timestamptz NOT NULL DEFAULT now(), processed_at timestamptz);
  const { rowCount } = await db.query(
    `INSERT INTO stripe_events (id, type, payload) VALUES ($1, $2, $3)
     ON CONFLICT (id) DO NOTHING`,
    [event.id, event.type, event],
  );

  // Stored durably, so this 200 is a promise the server can keep. The row is
  // picked up by a worker that marks processed_at in the same transaction as
  // the business effect; rowCount 0 means the id was already there.
  res.status(200).json({ received: true, duplicate: rowCount === 0 });
});

What should the endpoint return?

Receive Stripe webhooks through a verified HookGet source

Receiving Stripe webhooks through HookGet

The contract

Setting it up

# 1. create a verified source; the secret is shown once
curl -X POST https://api.hookget.com/v1/sources \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{"provider":"stripe","name":"Production"}'

# {"id":"src_…","secret":"whsec_…","ingest_path":"/ingest/src_…"}

1. In the Stripe dashboard, open Developers → Webhooks → Add endpoint.
2. Paste the ingest URL. Stripe issues its own signing secret — put that value into the HookGet source as the secret.
3. Select the event types you need.

What you get after verification