<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Payment Circle </title>
    <description>The latest articles on DEV Community by Payment Circle  (@paymentcircle124).</description>
    <link>https://dev.to/paymentcircle124</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4241552%2Fc46f07f9-fa4e-4887-882b-c84843e0884a.png</url>
      <title>DEV Community: Payment Circle </title>
      <link>https://dev.to/paymentcircle124</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/paymentcircle124"/>
    <language>en</language>
    <item>
      <title>Payment Webhooks Explained: How to Handle Failed, Duplicate, and Out-of-Order Events</title>
      <dc:creator>Payment Circle </dc:creator>
      <pubDate>Fri, 13 Nov 2026 22:04:17 +0000</pubDate>
      <link>https://dev.to/paymentcircle124/payment-webhooks-explained-how-to-handle-failed-duplicate-and-out-of-order-events-36d3</link>
      <guid>https://dev.to/paymentcircle124/payment-webhooks-explained-how-to-handle-failed-duplicate-and-out-of-order-events-36d3</guid>
      <description>&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F85a9a6ep45sbm6srdx10.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F85a9a6ep45sbm6srdx10.webp" alt="Payment webhook architecture showing event delivery from a payment provider to a webhook endpoint, durable queue, background worker, and database" width="800" height="533"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;A customer completes an online payment. The payment provider verifies the transaction, although the order is marked as unpaid in your application.&lt;/p&gt;

&lt;p&gt;Or worse, the same payment notification arrives twice, triggering duplicate fulfillment.&lt;/p&gt;

&lt;p&gt;These problems often originate from how an application handles &lt;strong&gt;payment webhooks&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Webhooks allow payment providers to notify applications when transactions change status. However, reliable webhook handling requires more than creating an HTTP endpoint and updating an order record.&lt;/p&gt;

&lt;p&gt;Network failures, repeated deliveries, asynchronous processing, and unexpected event ordering can all cause inconsistencies.&lt;/p&gt;

&lt;p&gt;In this guide, we'll explain how payment webhooks work, why delivery problems occur, and how developers can build reliable webhook handlers using signature verification, idempotency, durable storage, and background processing.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. What Are Payment Webhooks?
&lt;/h2&gt;

&lt;p&gt;A payment webhook is an HTTP request that gets sent by the payment provider to the application whenever something interesting happens.&lt;/p&gt;

&lt;p&gt;Instead of repeatedly requesting payment status through an API, your backend receives notifications when the provider reports changes.&lt;/p&gt;

&lt;p&gt;Common payment events include:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Payment successfully completed.&lt;/li&gt;
&lt;li&gt;Payment authorization failed.&lt;/li&gt;
&lt;li&gt;Refund processed.&lt;/li&gt;
&lt;li&gt;Chargeback or dispute created.&lt;/li&gt;
&lt;li&gt;Subscription payment succeeded or failed.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;For example, a webhook integration may follow this sequence:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;A customer submits a payment.&lt;/li&gt;
&lt;li&gt;The payment provider processes the transaction.&lt;/li&gt;
&lt;li&gt;The provider generates an event.&lt;/li&gt;
&lt;li&gt;The event is sent to your webhook using an HTTP POST method.&lt;/li&gt;
&lt;li&gt;Your backend validates and records the event.&lt;/li&gt;
&lt;li&gt;A worker updates the application's payment or order state.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The webhook informs your application that something happened. It should not automatically be treated as permission to perform every downstream action without verification.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Why Payment Webhooks Fail
&lt;/h2&gt;

&lt;p&gt;Even when a payment succeeds, its webhook delivery may fail.&lt;/p&gt;

&lt;h3&gt;
  
  
  Network and Server Failures
&lt;/h3&gt;

&lt;p&gt;Temporary network interruptions, unavailable servers, or DNS problems can prevent notifications from reaching your application.&lt;/p&gt;

&lt;h3&gt;
  
  
  Slow Webhook Handlers
&lt;/h3&gt;

&lt;p&gt;If a webhook endpoint performs several database queries, sends emails, and calls external APIs before responding, it may exceed the provider's response deadline.&lt;/p&gt;

&lt;p&gt;The provider may interpret the delivery as unsuccessful and retry.&lt;/p&gt;

&lt;h3&gt;
  
  
  Application Errors
&lt;/h3&gt;

&lt;p&gt;Malformed requests, unexpected event types, and unhandled exceptions can prevent successful processing.&lt;/p&gt;

&lt;h3&gt;
  
  
  Temporary Database Failures
&lt;/h3&gt;

&lt;p&gt;An event may reach your server while its database is unavailable.&lt;/p&gt;

&lt;p&gt;If the application acknowledges the webhook before storing it reliably, the notification may be lost.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Key principle:&lt;/strong&gt; Receiving a webhook is not the same as successfully processing its associated business operation.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Why Duplicate Webhook Events Happen
&lt;/h2&gt;

&lt;p&gt;The payment provider might send you the event multiple times.&lt;/p&gt;

&lt;p&gt;Suppose a provider sends a successful payment notification.&lt;/p&gt;

&lt;p&gt;Your server updates the order but crashes before returning an HTTP response.&lt;/p&gt;

&lt;p&gt;As the payment provider never receives any confirmation, it keeps trying to send the event.&lt;/p&gt;

&lt;p&gt;Without duplicate protection, your application might:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Create a second fulfillment request.&lt;/li&gt;
&lt;li&gt;Send duplicate confirmation emails.&lt;/li&gt;
&lt;li&gt;Record the same payment twice.&lt;/li&gt;
&lt;li&gt;Grant the same subscription entitlement repeatedly.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This is why payment webhook handlers need &lt;strong&gt;idempotency&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Idempotency means repeating an operation produces the same intended result without creating additional unintended effects.&lt;/p&gt;

&lt;h3&gt;
  
  
  Event-Level vs. Business-Level Idempotency
&lt;/h3&gt;

&lt;p&gt;Event-level deduplication prevents your application from processing the same notification ID repeatedly.&lt;/p&gt;

&lt;p&gt;Business-level idempotency prevents duplicate operations even when different event notifications refer to the same underlying payment.&lt;/p&gt;

&lt;p&gt;Both matter.&lt;/p&gt;

&lt;p&gt;For example, two distinct notifications could reference the same successful payment. Recording unique event IDs alone does not guarantee that an order will only be fulfilled once.&lt;/p&gt;

&lt;p&gt;A stronger design uses a unique business identifier, such as an order ID or payment ID, to protect fulfillment operations.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Verify Webhook Signatures Before Processing
&lt;/h2&gt;

&lt;p&gt;Never assume a request is trustworthy simply because it reaches your webhook URL.&lt;/p&gt;

&lt;p&gt;An attacker could submit fabricated payment notifications to an unsecured endpoint.&lt;/p&gt;

&lt;p&gt;Payment providers use different authentication mechanisms, including cryptographic signatures, to help applications verify webhook authenticity and integrity.&lt;/p&gt;

&lt;p&gt;For signed webhooks, verification generally involves:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Receiving the original webhook payload.&lt;/li&gt;
&lt;li&gt;Reading the provider's signature information.&lt;/li&gt;
&lt;li&gt;Validating the signature using the appropriate secret or verification key.&lt;/li&gt;
&lt;li&gt;Rejecting requests that fail verification.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The exact procedure is provider-specific.&lt;/p&gt;

&lt;p&gt;For instance, Stripe's Node.js SDK provides &lt;code&gt;constructEvent()&lt;/code&gt; for verifying supported signed webhook events.&lt;/p&gt;

&lt;p&gt;For this, it needs the original request body as parsing JSON invalidates the signature check.&lt;/p&gt;

&lt;h3&gt;
  
  
  Example: Verifying Stripe Webhooks in Node.js
&lt;/h3&gt;

&lt;p&gt;The following example uses Express, Stripe's SDK, and PostgreSQL.&lt;/p&gt;

&lt;p&gt;Install the dependencies:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm install express stripe pg dotenv
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Create a PostgreSQL table for storing events:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;webhook_inbox&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;event_id&lt;/span&gt; &lt;span class="kt"&gt;TEXT&lt;/span&gt; &lt;span class="k"&gt;PRIMARY&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;event_type&lt;/span&gt; &lt;span class="kt"&gt;TEXT&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;payload&lt;/span&gt; &lt;span class="kt"&gt;JSONB&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="kt"&gt;TEXT&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="s1"&gt;'pending'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;received_at&lt;/span&gt; &lt;span class="kt"&gt;TIMESTAMPTZ&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="nb"&gt;NOW&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now create the webhook endpoint:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nb"&gt;require&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"dotenv"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;config&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;express&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"express"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nc"&gt;Stripe&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"stripe"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Pool&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"pg"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;express&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;stripe&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;STRIPE_SECRET_KEY&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Pool&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;connectionString&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;DATABASE_URL&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="s2"&gt;"/webhooks/stripe"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"application/json"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;webhooks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;constructEvent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"stripe-signature"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;STRIPE_WEBHOOK_SECRET&lt;/span&gt;
      &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Invalid webhook signature"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="sb"&gt;`INSERT INTO webhook_inbox
         (event_id, event_type, payload)
         VALUES ($1, $2, $3)
         ON CONFLICT (event_id) DO NOTHING`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
      &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Webhook storage failed"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sendStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;500&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Register JSON parsing after the webhook route.&lt;/span&gt;
&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;use&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;express&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;listen&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;3000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The endpoint performs three important operations:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Validates the webhook signature.&lt;/li&gt;
&lt;li&gt;Stores each event using a unique event ID.&lt;/li&gt;
&lt;li&gt;Returns an acknowledgment only after the database write succeeds.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If the same event arrives again, PostgreSQL ignores the duplicate insertion.&lt;/p&gt;

&lt;p&gt;If the database operation fails, the endpoint returns an error so the provider can retry according to its delivery policy.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Important:&lt;/strong&gt; This is an illustrative receiver, not a complete production payment integration. It assumes a compatible Stripe snapshot-event payload and properly configured credentials, database access, and endpoint security. It also needs a background worker to process stored events.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Why You Should Process Webhooks Asynchronously
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fqr9t0qsyb7zm4xy888b7.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fqr9t0qsyb7zm4xy888b7.webp" alt="Payment webhook architecture diagram showing events flowing from a payment provider through a webhook endpoint and durable queue to a background worker and database" width="800" height="450"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Webhook handlers should acknowledge valid events quickly.&lt;/p&gt;

&lt;p&gt;A good design keeps event reception separate from business logic:&lt;/p&gt;

&lt;p&gt;Payment Provider → Webhook Endpoint → Durable Inbox or Queue → Background Worker → Business Database&lt;/p&gt;

&lt;p&gt;The webhook endpoint verifies and stores the notification.&lt;/p&gt;

&lt;p&gt;A background worker processes it independently.&lt;/p&gt;

&lt;p&gt;This design offers several advantages:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Shorter webhook response times.&lt;/li&gt;
&lt;li&gt;Better handling of temporary service failures.&lt;/li&gt;
&lt;li&gt;Controlled processing during traffic spikes.&lt;/li&gt;
&lt;li&gt;Easier retries and error investigation.&lt;/li&gt;
&lt;li&gt;Reduced risk of losing accepted notifications.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;In the PostgreSQL example, the webhook_inbox table acts as a durable inbox.&lt;/p&gt;

&lt;p&gt;A worker can select pending events, process them, and update their status.&lt;/p&gt;

&lt;p&gt;For concurrent workers, PostgreSQL's FOR UPDATE SKIP LOCKED can help prevent multiple workers from claiming the same event simultaneously.&lt;/p&gt;

&lt;p&gt;However, event processing must also be transactionally safe.&lt;/p&gt;

&lt;p&gt;A worker crash between fulfillment and marking an event complete can still cause repeated side effects.&lt;/p&gt;

&lt;h2&gt;
  
  
  Protect the Business Operation
&lt;/h2&gt;

&lt;p&gt;For example, if fulfillment is represented in PostgreSQL, define a uniqueness constraint:&lt;/p&gt;

&lt;p&gt;CREATE TABLE fulfilled_orders (&lt;br&gt;
  order_id TEXT PRIMARY KEY,&lt;br&gt;
  payment_id TEXT NOT NULL UNIQUE,&lt;br&gt;
  fulfilled_at TIMESTAMPTZ DEFAULT NOW()&lt;br&gt;
);&lt;/p&gt;

&lt;p&gt;A worker can insert the fulfillment record using ON CONFLICT DO NOTHING, making the database operation repeat-safe.&lt;/p&gt;

&lt;p&gt;The worker should apply relevant order changes and mark the inbox event processed within a suitable database transaction.&lt;/p&gt;

&lt;p&gt;External operations, such as sending emails or calling shipping services, need their own idempotency strategy. A transactional outbox or a fulfillment API supporting idempotency keys can help.&lt;/p&gt;

&lt;p&gt;The goal is not merely to prevent duplicate database rows. It is to prevent duplicate real-world actions.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. How to Handle Out-of-Order Webhook Events
&lt;/h2&gt;

&lt;p&gt;Webhook events are not always delivered in the order they occurred.&lt;/p&gt;

&lt;p&gt;Imagine this sequence:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;A payment attempt fails.&lt;/li&gt;
&lt;li&gt;The customer retries successfully.&lt;/li&gt;
&lt;li&gt;The successful payment event reaches your application.&lt;/li&gt;
&lt;li&gt;A delayed failure event arrives afterward.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If your application blindly applies each notification, the delayed failure could incorrectly change a paid order back to an unpaid state.&lt;/p&gt;

&lt;p&gt;A robust webhook implementation should not assume arrival order equals business-event order.&lt;/p&gt;

&lt;h2&gt;
  
  
  Use Valid Payment State Transitions
&lt;/h2&gt;

&lt;p&gt;Define the states your application supports.&lt;/p&gt;

&lt;p&gt;For example:&lt;/p&gt;

&lt;p&gt;pending → authorized → paid&lt;/p&gt;

&lt;p&gt;Other possible transitions may include:&lt;/p&gt;

&lt;p&gt;pending → failed&lt;/p&gt;

&lt;p&gt;paid → partially_refunded&lt;/p&gt;

&lt;p&gt;paid → refunded&lt;/p&gt;

&lt;p&gt;These are illustrative application states, not a universal payment-provider state machine.&lt;/p&gt;

&lt;p&gt;A delayed notification should not automatically override a newer confirmed payment state.&lt;/p&gt;

&lt;h2&gt;
  
  
  Retrieve Current Provider State When Necessary
&lt;/h2&gt;

&lt;p&gt;When event ordering affects a business decision, retrieve the current payment or subscription state from the provider's API.&lt;/p&gt;

&lt;p&gt;For instance, before changing an order from paid to failed, the application can verify the actual current status of the associated payment.&lt;/p&gt;

&lt;p&gt;Always follow the provider's documented event semantics. Some events represent independent historical facts rather than updates that should overwrite a single status field.&lt;/p&gt;

&lt;h2&gt;
  
  
  7.  Handle Retries Without Creating New Problems
&lt;/h2&gt;

&lt;p&gt;Retries are essential because distributed systems experience temporary failures.&lt;/p&gt;

&lt;p&gt;A well-designed webhook consumer should distinguish between transient errors and permanent failures.&lt;/p&gt;

&lt;p&gt;Transient errors may include temporary database outages, timeouts, or unavailable dependencies.&lt;/p&gt;

&lt;p&gt;These can often be retried safely.&lt;/p&gt;

&lt;p&gt;Permanent errors may include invalid payloads, unsupported event formats, or data that cannot be processed without intervention.&lt;/p&gt;

&lt;p&gt;Repeatedly retrying a permanently invalid event may create unnecessary load.&lt;/p&gt;

&lt;p&gt;For background processing, use bounded retries with exponential backoff and jitter.&lt;/p&gt;

&lt;p&gt;After repeated failures, move the event into a failed or dead-letter state so it can be investigated.&lt;/p&gt;

&lt;p&gt;Importantly, returning HTTP 200 to a payment provider should mean that the event has been safely accepted, not necessarily that every downstream operation has finished.&lt;/p&gt;

&lt;p&gt;If an event cannot be stored reliably, do not acknowledge it as successfully accepted.&lt;/p&gt;

&lt;h2&gt;
  
  
  8. Test These Payment Webhook Scenarios
&lt;/h2&gt;

&lt;p&gt;Before deploying a payment webhook integration, developers should test more than successful payment transactions. A reliable implementation must handle unexpected events, repeated notifications, and temporary system failures without creating payment inconsistencies.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Valid Webhook Events:&lt;/strong&gt; Verify that legitimate webhook requests pass signature verification, are stored successfully, and receive an appropriate acknowledgment.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Invalid Signatures:&lt;/strong&gt; Submit a webhook request with an invalid signature and confirm that the application rejects it without processing the event.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Duplicate Event IDs:&lt;/strong&gt; Send the same webhook event multiple times and verify that it is not processed repeatedly.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Multiple Events for One Payment:&lt;/strong&gt; Test different webhook events referencing the same payment and confirm that they do not trigger duplicate order fulfillment.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Out-of-Order Events:&lt;/strong&gt; Deliver an older notification after a newer one and verify that the application preserves the correct payment status.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Temporary Database Failures:&lt;/strong&gt; Simulate a database outage and confirm that the webhook endpoint returns an error when it cannot reliably store the event.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Background Worker Failures:&lt;/strong&gt; Simulate a worker crashing during processing and verify that the event can be retried without duplicating business operations.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Unsupported Event Types:&lt;/strong&gt; Submit events that the application does not handle and confirm that they are safely ignored or recorded without unintended effects.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;High Webhook Traffic:&lt;/strong&gt; Simulate a sudden increase in incoming notifications and verify that the application can accept, queue, and process events without overwhelming its workers.&lt;/p&gt;

&lt;p&gt;Also test recovery after prolonged downtime and ensure monitoring can identify events that remain unprocessed.&lt;/p&gt;

&lt;p&gt;Use your payment provider's sandbox or testing environment rather than actual customer transactions.&lt;/p&gt;

&lt;h2&gt;
  
  
  9. Production-Ready Payment Webhook Checklist
&lt;/h2&gt;

&lt;p&gt;Before deploying, confirm that your implementation:&lt;/p&gt;

&lt;p&gt;Uses HTTPS and verifies webhook authenticity.&lt;/p&gt;

&lt;p&gt;Preserves the raw request body when required for signature verification.&lt;/p&gt;

&lt;p&gt;Stores accepted events durably.&lt;/p&gt;

&lt;p&gt;Implements event-level deduplication.&lt;/p&gt;

&lt;p&gt;Protects payment-related business operations against duplicates.&lt;/p&gt;

&lt;p&gt;Handles notifications arriving out of order.&lt;/p&gt;

&lt;p&gt;Processes slow operations outside the HTTP request.&lt;/p&gt;

&lt;p&gt;Retries recoverable failures safely.&lt;/p&gt;

&lt;p&gt;Logs event IDs, processing status, and relevant errors.&lt;/p&gt;

&lt;p&gt;Protects signing secrets and sensitive payment information.&lt;/p&gt;

&lt;p&gt;Provides a recovery process for failed or missed notifications.&lt;/p&gt;

&lt;p&gt;Avoid logging complete sensitive payment data or exposing webhook secrets in application logs.&lt;/p&gt;

&lt;p&gt;These controls help make the payment integration more reliable as transaction volume grows.&lt;/p&gt;

&lt;h2&gt;
  
  
  Final Thoughts
&lt;/h2&gt;

&lt;p&gt;Payment webhooks are a critical connection between payment infrastructure and application business logic.&lt;/p&gt;

&lt;p&gt;A successful integration must do more than receive notifications.&lt;/p&gt;

&lt;p&gt;It needs to verify incoming events, preserve delivery information, prevent duplicate operations, handle unexpected ordering, and recover from failures.&lt;/p&gt;

&lt;p&gt;The most important design principle is straightforward:&lt;/p&gt;

&lt;p&gt;Treat webhooks as reliable inputs only after verification, and design every downstream payment operation to tolerate retries and unexpected delivery order.&lt;/p&gt;

&lt;p&gt;That approach helps developers maintain accurate order states, prevent duplicate fulfillment, and build payment systems that remain dependable as businesses scale.&lt;/p&gt;

&lt;h2&gt;
  
  
  Technical References
&lt;/h2&gt;

&lt;p&gt;The following official resources provide additional technical guidance on webhook implementation, security, and event handling.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe — Webhooks&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/stripe/stripe-node" rel="noopener noreferrer"&gt;Stripe Node.js SDK — Webhook Signature Verification&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://docs.adyen.com/development-resources/webhooks/handle-webhook-events" rel="noopener noreferrer"&gt;Adyen — Handle Webhook Events&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://cheatsheetseries.owasp.org/cheatsheets/Webhook_Security_Cheat_Sheet.html" rel="noopener noreferrer"&gt;OWASP — Webhook Security Cheat Sheet&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;AI Disclosure: This article was generated with AI assistance. Code examples are illustrative and should be independently reviewed and tested before production use.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>api</category>
      <category>architecture</category>
      <category>backend</category>
      <category>webdev</category>
    </item>
  </channel>
</rss>
