Ensuring Robust Stripe Webhook Processing: Addressing Delayed Event Failures in ESHOPMAN

Reliable payment processing is the bedrock of any successful e-commerce operation. For ESHOPMAN merchants leveraging Stripe, ensuring every payment event is accurately captured and processed is paramount. A recent technical discussion within the ESHOPMAN community has shed light on a subtle yet critical timing-related issue that could lead to dropped Stripe webhook events, impacting transaction integrity and requiring manual intervention.

The Challenge: Stripe Webhook Signature Tolerance

The ESHOPMAN platform, built on Node.js/TypeScript, integrates seamlessly with Stripe for payment processing. When Stripe sends a webhook event (e.g., for a successful payment), ESHOPMAN's backend receives it at the /hooks/payment/:provider route. The current processing flow involves two key steps:

1. The ESHOPMAN route immediately responds with a 200 OK status to Stripe, signaling successful receipt of the event.
2. The event data is then queued for asynchronous processing by a subscriber job, which includes verifying the Stripe webhook signature.

The core of the problem lies in Stripe's signature verification mechanism. Stripe includes a timestamp in the webhook signature, and its client libraries (like stripe-node) enforce a default tolerance of 300 seconds (5 minutes) between the timestamp in the signature and the time the signature is verified. If the ESHOPMAN queued job begins processing the webhook more than 5 minutes after Stripe originally signed it, the signature verification will fail with a "Timestamp outside the tolerance zone" error.

Crucially, because ESHOPMAN's initial route responds with a 200 OK, Stripe considers the delivery successful and will not attempt to resend the webhook. This means that even if the queued job fails due to the timestamp issue, the payment event is effectively lost within ESHOPMAN, requiring manual recovery from the Stripe Dashboard or CLI.

Technical Deep Dive into ESHOPMAN's Processing

The issue highlights a specific interaction within ESHOPMAN's payment processing modules. The initial webhook receipt route queues an event (e.g., payment.webhook_received) with details like the raw body, parsed body, and request headers. The signature verification itself is performed later when the subscriber job runs, utilizing Stripe's constructEvent function without explicitly passing a receivedAt timestamp or a custom tolerance.

The relevant package versions observed in the discussion include:

"@eshopman/eshopman": "2.21.2",
"@eshopman/payment-stripe": "2.21.2"

This behavior can be reproduced, showing that a delivery accepted initially by the route fails when the job starts just over 300 seconds later:

| | receipt → job | result |
|---|---|---|
| route, Stripe-signed delivery | — | `200`, queued as received, payment module not called |
| route, delivery with a bogus signature | — | `200`, queued as received |
| job | +10 s | accepted, `process-payment-workflow` started with `action: "captured"` |
| job, all three attempts | +301 s, +302 s, +303 s | `An error occurred in constructWebhookEvent: Timestamp outside the tolerance zone`, workflow never started |

Proposed Solutions and Best Practices

The ESHOPMAN community has identified two primary approaches to mitigate this issue and ensure robust Stripe webhook processing:

1. Record Receipt Time: The most straightforward solution involves recording the exact time the webhook is received at the ESHOPMAN route and passing this receivedAt timestamp to Stripe's constructEvent function. This ensures that the signature verification uses the original receipt time, not the potentially delayed job execution time, thereby respecting Stripe's tolerance.

2. Verify Early: Alternatively, the Stripe signature could be verified immediately within the ESHOPMAN webhook route. If the signature is invalid (or outside tolerance at receipt), the route could respond with a 400 status, prompting Stripe to potentially retry the delivery. Only verified events would then be queued for further processing.

The first option is generally preferred as it maintains the asynchronous processing flow while resolving the timing issue effectively.

Impact for ESHOPMAN Merchants and Developers

This insight is crucial for ESHOPMAN merchants relying on Stripe, especially those with high transaction volumes or complex queueing infrastructures for their Node.js backend. Unprocessed payments can lead to customer dissatisfaction, administrative overhead, and potential revenue loss. For ESHOPMAN developers, understanding this mechanism is vital for building resilient integrations and ensuring the integrity of payment workflows within the HubSpot-integrated commerce platform.

The ESHOPMAN team and community are actively working on implementing a robust solution to address this, reinforcing the platform's commitment to reliable headless commerce operations.