Stay within limits: API rate-limit-friendly pattern for Stripe webhooks

Summary

Stripe webhook handlers that treat events as signals and fetch the latest resource can preserve correctness when payloads are stale, partial, duplicated, or out of order, but bursts of events can drive excessive API traffic. The post describes Stripe’s general limit as 100 read requests per second and notes that exceeding it produces 429 responses. Its solution places Hookdeck Event Gateway between Stripe and the application: Hookdeck authenticates and queues incoming webhooks, throttles delivery, and lets the handler retrieve the current Stripe resource at a controlled pace. The Express.js flow verifies the Hookdeck signature, checks the event and resource ID, fetches the invoice with the Stripe SDK, and supports queue monitoring, alerts, and retries for backpressure.

Context

Fetching the latest Stripe resource before processing helps handle stale or partial webhook payloads, duplicate events, and events arriving out of order. At higher volumes, bursts such as flash sales, migrations, or subscription renewals can generate enough API requests to exceed Stripe’s general 100 read-requests-per-second limit and trigger 429 responses.

Approach / What changed

Route Stripe webhooks through a Hookdeck Connection, authenticate them with the Stripe signing secret, and configure a maximum delivery rate. Hookdeck queues incoming events and delivers them to the application at the selected pace; the Express.js endpoint verifies the Hookdeck signature, validates the event and invoice ID, and retrieves the current invoice through the Stripe SDK. Queue depth, delivery delays, alerts, and retries provide operational visibility and backpressure handling.

Takeaways

• The fetch-before-process pattern retrieves the current Stripe resource immediately before handling an event, reducing the impact of stale snapshots, duplicate deliveries, and incorrect event order.
• The setup uses a 25-requests-per-second delivery rate for a sandbox environment and suggests increasing it to 100 requests per second in production.
• Hookdeck’s queue exposes queue depth and delivery delays, supports alerts when backpressure builds, and allows failed events to be retried manually or automatically.

Related reading