Receive Stripe webhooks through Queuey

Do you need anything between Stripe and your handler?

Not always. Stripe's webhooks are well built: signed, retried, resendable. That is also why a queue in between costs you nothing in safety — Stripe's retries now cover the hop into Queuey, an ingress built to accept and store. What Stripe cannot do is run your side of the connection, and that is where events get lost: a deploy that returns 500 for an afternoon, a bug that throws on one event type for a week, a handler that does its work before it answers and times out on the first of the month. The honest comparison — the same reasoning for any provider is on its own page:

When it is not worth adding. Your endpoint already does nothing but verify, write to a durable queue you operate, and return 2xx — and you are content with the dead-letter handling, replay and visibility you have there: Queuey would replace that plumbing, not close a gap. Or the events are low-stakes, the handler is simple and idempotent, and three days of Stripe retries plus an occasional manual resend is enough. And the few event types Stripe waits on belong on a direct endpoint either way.

What it costs. One more hop and one more vendor in your payment event path. Stripe's retries still stand behind Queuey's ingress exactly as they stood behind your endpoint: an event Queuey cannot accept is retried by Stripe, the same as before.

5 — Optional: keep verifying Stripe's signature in your handler, unchanged

Nothing requires this. It is for a handler that already calls constructEvent and should keep doing so. With Stripe signature recalculation on the queue, it keeps calling constructEvent exactly as it does today: the Stripe endpoint's whsec_… secret, no code change. Queuey signs Stripe's unchanged bytes again with a fresh timestamp on each attempt — first delivery, retries and replays — so your handler's constructEvent keeps working with the default tolerance. Only events that arrive through this queue's Stripe-verified ingress after you turn it on are signed.

Turn it on under Delivery → Request signing: tick Recalculate the Stripe signature on every delivery. Queuey signs with the secret this queue's Stripe ingress verifies with — the signing secret of the Stripe endpoint from step 2 — and with no other, so a handler that used to receive from that endpoint directly already has it (see moving an existing endpoint); a handler that verified another endpoint needs this one's secret. The checkbox is there only when the queue's ingress verifies Stripe as in step 3, and only on the queue itself, not as a workspace default. It takes the place of Queuey HMAC rather than adding to it: a queue signs one way.

What Queuey signs, and what it refuses

Queuey signs an event as Stripe only if it arrived through the queue's ingress after recalculation started, and only with the secret the ingress verified it with. While recalculation is on, the ingress can't be switched away from verifying Stripe, and giving it another secret starts recalculation again, so every event Queuey signs passed the check from step 3 with that secret. Recalculation starts 30 seconds after you save — the longest the ingress can take to pick up a changed setting — and the queue shows when. On every delivery attempt Queuey then signs the stored bytes: t is the time of this attempt, and v1 is HMAC-SHA256 over {t}.{raw body}. Stripe does the same on its own retries and when you use Resend in its Dashboard: a fresh t every time, while the event's own time stays in the body as created. So a retry after an outage, a queue that was held and a replay from the dead-letter queue all reach your handler with a signature seconds old. It refuses three things:

• Events from before recalculation started. An event that arrived earlier — for example while the queue's ingress was still open — is not signed as Stripe: it goes to the dead-letter queue with failure class OriginNotVerified, and the rest of the queue keeps delivering. Resend in Stripe brings it back as a new event. A test delivery typed in the console is refused the same way, with the reason in its result, because Stripe never sent it. To test the path, send a real event: stripe trigger in a Stripe sandbox, or Resend in Stripe.
• Bodies Queuey has changed. A queue that recalculates the Stripe signature cannot have a Transform Map or payload patches — its own or inherited from the workspace — and its payload format must be Raw (as received). The combination is refused when you save.
• A second Stripe-Signature. The header belongs to the signature, so it cannot also be a static header, a mapped header or the GroupKey header. That is also why recalculating the signature and forwarding Stripe's own one, below, cannot share a queue.

A receiver you do not run. A service that accepts Stripe webhooks verifies them with the signing secret you give it. Give it the secret of the Stripe endpoint from step 2: Queuey signs with that secret and no other, so a service that insists on a secret of its own can't sit behind this queue — give it a Stripe endpoint of its own instead.

Your handler still deduplicates on Stripe's event id. A valid signature does not mean a first delivery: Queuey's retries and replays deliver the same event again, each signed afresh, just as Stripe's own retries do — and Stripe already asks you to skip the ids you have processed. Keep the API key from step 4 as well, as defence in depth: the signature vouches for the bytes, the key for the caller.

If you want proof independent of Queuey: forward Stripe's own signature

With recalculation, the v1 your handler checks was made by Queuey, with your secret, after Queuey checked Stripe's. If the handler should check a signature Stripe made itself, forward Stripe's header instead. The two cannot be combined on one queue — Stripe-Signature cannot be both mapped and recalculated — so leave recalculation off, leave the payload format on Raw (as received) — the default — and add one mapped header under Delivery → Payload & ordering:

Sends header        ←   Read from the incoming request
Stripe-Signature    ←   Header: Stripe-Signature

Queuey reads the header off Stripe's request when the event is accepted, stores it with the event, and sends that stored value on every delivery attempt. Leave required off: with the Stripe template on, a request without the header never gets this far. Because the body is forwarded byte for byte, the signature still matches. Content-Type arrives without Stripe's charset parameter, which does not matter: the signature covers the timestamp and the body only. Use it together with the API key from step 4, not instead of it.

The price is the tolerance. Stripe's libraries reject a signature whose timestamp is more than five minutes old, and a forwarded signature keeps the timestamp Stripe gave it when it sent the event. A first delivery reaches your handler within moments, well inside the window. A retry after your handler was down, a queue that was held, or a replay from the dead-letter queue does not. With the default tolerance that delivery fails verification and your handler answers 400. Queuey reads a 400 as the receiver rejecting that event: it is not retried, it goes to the dead-letter queue — and replaying it cannot help, because a forwarded signature only gets older. The events Queuey exists to save would be exactly the ones your handler refuses. Recalculation removes that problem; forwarding has to work around it.

So pass a tolerance that covers the longest an event may wait in Queuey. Your plan's retention window is the upper bound:

const secret = process.env.STRIPE_WEBHOOK_SECRET!; // the same whsec_… Queuey verifies with

// The longest an event may wait in Queuey and still be delivered — a retry
// after an outage, or a replay from the dead-letter queue. In seconds.
const TOLERANCE = 7 * 24 * 60 * 60;

app.post("/webhooks/stripe", express.raw({ type: "application/json" }), (req, res) => {
  if (!isQueuey(req.get("X-Api-Key"))) return res.sendStatus(401); // step 4 stays in front

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,                     // the raw bytes, never a parsed object
      req.get("Stripe-Signature")!, // forwarded by Queuey exactly as Stripe sent it
      secret,
      TOLERANCE,                    // the library default is 300
    );
  } catch {
    return res.status(400).send("signature verification failed");
  }

  // Your own code from here. Deduplicate on event.id.
  res.sendStatus(200);
});

# The longest an event may wait in Queuey and still be delivered — a retry
# after an outage, or a replay from the dead-letter queue. In seconds.
TOLERANCE = 7 * 24 * 60 * 60


@app.post("/webhooks/stripe")
def stripe_webhook():
    presented = request.headers.get("X-Api-Key", "").encode()
    if not hmac.compare_digest(presented, delivery_key):  # step 4 stays in front
        return "", 401

    try:
        event = stripe.Webhook.construct_event(
            request.data,                             # the raw bytes
            request.headers.get("Stripe-Signature"),  # forwarded by Queuey as Stripe sent it
            os.environ["STRIPE_WEBHOOK_SECRET"],      # the same whsec_… Queuey verifies with
            tolerance=TOLERANCE,                      # the library default is 300
        )
    except (ValueError, stripe.SignatureVerificationError):
        return "signature verification failed", 400

    # Your own code from here. Deduplicate on event["id"].
    return "", 200

// The longest an event may wait in Queuey and still be delivered — a retry
// after an outage, or a replay from the dead-letter queue. In seconds.
const long Tolerance = 7 * 24 * 60 * 60;

// …after the API-key check from step 4, with the body read into json:
Event stripeEvent;
try
{
    stripeEvent = EventUtility.ConstructEvent(
        json,                                // the body exactly as received
        request.Headers["Stripe-Signature"], // forwarded by Queuey exactly as Stripe sent it
        config["Stripe:WebhookSecret"],      // the same whsec_… Queuey verifies with
        tolerance: Tolerance);               // the library default is 300
}
catch (StripeException)
{
    return Results.BadRequest("signature verification failed");
}

Use a real number rather than 0. Stripe's documentation says 0 switches the check off, which is true of most of its libraries — but Stripe.net compares against the value as it is, and would reject nearly every event.

Moving an existing endpoint

A Stripe signing secret belongs to the endpoint, not to its URL. You can therefore put Queuey in front of a handler that is already in production without issuing a new secret, without a gap — and, with Stripe signature recalculation, without changing the handler:

1. Set up the queue as in steps 1 and 3, with the secret your handler already uses. On the Delivery tab, give it the handler's current URL, tick Recalculate the Stripe signature on every delivery with the same secret (step 5), and set the API key from step 4 — a handler that does not check the key yet ignores the header. Switch the queue to Deliver.
2. In Stripe, edit the endpoint's URL to the queue's ingress URL. The secret stays the same; from the next event on, the path runs through Queuey, and your handler verifies each delivery the way it verified Stripe's. Rolling back is the same edit in reverse.
3. When Stripe's event deliveries show the new URL, add the API-key check to the handler when it suits you — defence in depth, not a condition for the move.

One thing can still stop deliveries: a handler or firewall that admits only Stripe's IP addresses. Change that before step 2 (step 5 says why). Without recalculation, the handler has to change first. To rely on the API key alone, make it accept both callers — a request with the key is Queuey, anything else goes through the Stripe check you already have — and deploy that before step 2. To forward the signature instead, widen its tolerance before step 2. Either way, avoid running two live Stripe endpoints side by side — one direct, one through Queuey — unless the queue stays in Log-only: your handler would get every event twice, signed with two different secrets.