Resilient Webhooks: How to Handle Payment Events Without Dropping the Ball

In payment processing, APIs handle the requests you initiate, but webhooks handle the reality of what happens next. Whether a subscription renews, a customer’s card gets declined, or a cross-border payment finally clears, asynchronous events rule the fintech landscape.

If your webhook endpoint drops a request, your database drifts out of sync. A customer pays, but their premium tier isn’t unlocked.

Building a bulletproof webhook consumer isn't just about setting up a POST route; it’s about defensive engineering. Here is how to handle Payrex webhooks securely and resiliently.

1. Verify the Payrex Signature

Never trust a payload blindly. Attackers can easily spoof HTTP POST requests to your endpoint. Every webhook sent by Payrex includes a Payrex-Signature header containing a timestamp and a cryptographic signature.

Always use our official SDKs to verify this signature against your endpoint's unique webhook secret.

‍

JavaScript

// Example using Node.js and Express
import express from 'express';
import { Payrex } from '@payrex/node';

const app = express();
const payrex = new Payrex('your_api_key');
const endpointSecret = process.env.PAYREX_WEBHOOK_SECRET;

// Match the exact raw body for signature verification
app.post('/webhooks/payrex', express.raw({ type: 'application/json' }), (req, res) => {
 const sig = req.headers['payrex-signature'];
 let event;

 try {
   // This verifies the signature and checks against replay attacks via timestamp
   event = payrex.webhooks.constructEvent(req.body, sig, endpointSecret);
 } catch (err) {
   console.error(`❌ Webhook Signature Verification Failed: ${err.message}`);
   return res.status(400).send(`Webhook Error: ${err.message}`);
 }

 // Handle the event
 if (event.type === 'payment_intent.succeeded') {
   const paymentIntent = event.data.object;
   // fulfillOrder(paymentIntent);
 }

 res.status(200).json({ received: true });
});

‍

2. Acknowledge Immediately, Process Later

Webhooks operate under a strict timeout window (typically 3–5 seconds). If your endpoint spends too much time processing heavy business logic—like spinning up a third-party shipping API, generating a PDF invoice, or executing deep database queries—Payrex will assume a timeout and retry the event.

The Golden Rule: Log the event, return a 200 OK status to Payrex immediately, and pass the payload to an asynchronous background worker or message queue (like Redis, RabbitMQ, or AWS SQS) for heavy lifting.

‍

[Payrex] ---> (POST /webhook) ---> [Your Express Endpoint]
                                        │
                                  (1. Quick Log & Validate)
                                        │
                                        ├──> [Return 200 OK to Payrex]
                                        │
                                  (2. Push to Redis/Queue) ──> [Background Worker Process]


‍

3. Design for Idempotency

Network disruptions happen. Payrex guarantees at-least-once delivery, which means in rare edge cases, you might receive the exact same webhook event twice.

If your backend isn’t prepared for duplicate events, you risk provisioning a feature twice or double-shipping an order.

• Every Payrex event payload contains a unique event.id.
• Before processing an event, check your database to see if event.id has already been recorded and successfully handled.
• If it has, skip the processing logic and simply return a 200 OK.

What to Expect from Payrex Retry Policies

If your server goes down or returns a 5xx error, Payrex doesn't just give up. Our system employs an exponential backoff algorithm that retries delivery over a 48-hour period. However, to prevent persistent failures from clogging your systems, ensure your endpoint remains lean, stateless, and heavily guarded by signature verification.

Happy coding!

‍