DEV Community: Jafar on Payments

How to Verify Payment Webhooks in Node.js (So You Never Ship an Order Twice)

Jafar on Payments — Thu, 05 Nov 2026 15:01:56 +0000

A customer pays for their order. A second later, your server gets the same "payment completed" message twice, and your system happily sends two parcels. Or worse, someone sends your server a fake "paid" message and walks away with a free order.

If you build checkouts or payment features in Node.js, payment webhooks are where these bugs live. This guide covers the five things you need to get right, with code you can copy.

What a payment webhook is

A webhook is a message your payment provider sends to your server when something happens, like "this payment succeeded" or "this refund failed". Instead of your app asking "is it paid yet?" every few seconds, the provider tells you.

That's handy, but it means your server has to answer three questions every time a message arrives:

Is this message really from my payment provider?
Have I already handled it?
Did I save it before replying "got it"?

Why the same webhook can arrive twice

Webhooks are usually delivered "at least once". If your server is slow, crashes or replies with an error, the provider sends the same message again, sometimes for many hours. The open Standard Webhooks specification, which many API companies follow, expects this and recommends giving every message a unique ID so you can spot repeats.

So duplicates aren't a rare edge case. They're normal, and your code has to expect them.

Step 1: Keep the raw request body

Most payment providers sign each webhook with HMAC-SHA256. That's a way of proving the message came from them and wasn't changed on the way. The signature is worked out from the exact bytes they sent.

If you parse the JSON and turn it back into text, those bytes can change (spacing, key order) and the check fails. So read the raw body on your webhook route:

import express from "express";
import crypto from "node:crypto";

const app = express();
const SECRET = process.env.WEBHOOK_SIGNING_SECRET;
const SIGNATURE_HEADER = "x-signature"; // use the header name in your provider's docs

app.post(
  "/webhooks/payments",
  express.raw({ type: "application/json" }), // keep the exact bytes
  async (req, res) => {
    if (!isValidSignature(req.body, req.get(SIGNATURE_HEADER))) {
      return res.status(401).end();
    }

    const event = JSON.parse(req.body.toString("utf8"));
    const isNew = await saveEventOnce(event); // save first...
    res.status(200).end();                    // ...then reply

    if (isNew) await processEvent(event);     // slow work last
  }
);

Step 2: Check the signature safely

function isValidSignature(rawBody, header) {
  if (!header) return false;
  const received = header.replace(/^v1=/, ""); // some providers add a version prefix
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(rawBody)
    .digest("hex");

  const a = Buffer.from(received, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Two details matter here. A normal === comparison can leak tiny timing differences that an attacker can measure, so use crypto.timingSafeEqual. And timingSafeEqual throws an error if the two values are different lengths, so check the length first.

Providers format signatures slightly differently (hex or base64, with or without a version prefix), so match these lines to your provider's webhook signature verification guide.

Step 3: Save each event only once

Handling repeats safely is called making your handler "idempotent": running it twice has the same effect as running it once. The simplest way is a unique key for every event and a database rule that rejects duplicates:

async function saveEventOnce(event) {
  // Use the event ID if your provider sends one
  const key = event.id ?? [event.type, event.paymentId, event.status].join(":");
  try {
    await db.webhookEvents.insert({ key, body: event }); // unique index on "key"
    return true;
  } catch (err) {
    if (err.code === "UNIQUE_VIOLATION") return false; // seen it before
    throw err;
  }
}

Step 4: Reply fast, then do the slow work

Providers only wait a short time for your reply. If you send emails, update stock or call other services first, the provider may give up and send the message again. This matters most at an online checkout, where a customer is staring at the confirmation page. Save the event, reply with 200, then do the slow work.

Step 5: Test it before real money moves

Use your provider's sandbox (a test version that uses fake money) to send test webhooks. Try three cases: a normal payment, the same message twice, and a message with a broken signature. Your code should handle the first, ignore the second and reject the third.

Checklist before you go live

The webhook route reads the raw body
Signatures are checked with a constant-time comparison
Every event is saved once, using a unique key
You reply 200 only after the event is saved
Duplicates and bad signatures are tested in the sandbox
A back-up job checks the status of any payment you haven't heard about

Conclusion

Webhooks are how your payment provider tells your app that money has moved, and most providers send them "at least once", so the same message can arrive twice. Keep the raw body, check the signature, save each event once and reply fast, and a retry will never turn into a second order. Run the checklist above in your sandbox before you switch on live payments.

How to Get Paid on Time: Practical Advice for Consultants and Agencies

Jafar on Payments — Wed, 09 Sep 2026 07:13:21 +0000

Finishing a project does not always mean getting paid for it. An agency may deliver on schedule and receive the client’s approval, yet wait weeks for the invoice to clear. For consultants and agencies with salaries, freelancers, software subscriptions and tax bills to cover, even a small delay can put pressure on cash flow.

Learning how to get paid on time is not simply about sending more reminders. Payment needs to be considered when the client is assessed, the contract is written and the project is divided into stages. The invoice itself is only one part of that process.

Why Clients Pay Invoices Late

Late payment does not always indicate that a client is unwilling to pay. An invoice can be delayed because it was sent to the project manager instead of accounts payable, omitted a purchase-order number or arrived after the cut-off for the next payment run.

There may also be a disagreement about whether a milestone has been completed. In other cases, the client intends to pay but puts it off because the payment process requires several manual steps.

Consider an agency that completes the first stage of a website project on Friday. It issues the invoice the following Wednesday and sends it to the marketing manager. The manager forwards it to finance several days later, but finance rejects it because there is no purchase-order number.

By the time the corrected invoice reaches the next payment run, almost three weeks have passed. The problem did not begin when the client missed a deadline. It began when the agency failed to understand the client’s payment process.

Check the Client Before Starting

Consultants and agencies usually assess whether they can deliver the requested work. They should also consider whether the client is likely to pay for it.

Confirm the client’s legal business name, billing address and company number where applicable. For a higher-value project, a basic search through Companies House can help confirm that the business is active and that the contract names the correct legal entity.

Ask the client how new suppliers are approved. Larger organisations may require vendor onboarding, insurance documents, tax information, a purchase order or registration on an invoicing portal.

It also helps to understand the payment timetable. If invoices are processed once a month, missing an internal approval deadline could add several weeks to the wait.

Payment history should influence future terms. An established client that has consistently paid on time may justify greater flexibility than a new customer requesting a large amount of work on extended credit.

Set Clear Payment Terms

Payment terms should be agreed before work begins, not introduced at the bottom of the first invoice.

The contract should state:

The agreed price and whether VAT applies
When invoices will be issued
The number of days allowed for payment
The payment methods available
How additional work will be approved and charged
How disputed invoices will be handled
Whether work may be paused when payment is overdue

Use an exact payment period. “Payment is due within 14 calendar days of the invoice date” is clearer than “payment due promptly.” Each invoice should also show a specific due date.

Consultants sometimes offer 30- or 60-day terms automatically because they assume larger clients will not accept anything else. However, long payment terms can leave the supplier financing the project. If an agency must pay employees and contractors before receiving the client’s money, the terms should reflect that risk.

Request an Upfront Deposit

A deposit is useful when a project requires substantial work or expenditure before the first deliverable is completed. It confirms the client’s commitment and provides funds for initial costs such as research, software, travel or freelance support.

There is no standard deposit that suits every project. Some consultants request 25% upfront, while agencies working on shorter projects may ask for 50%. Another option is to charge for the first phase in full before work starts.

The contract should explain when the deposit is due, whether it is refundable and what happens if the client cancels or postpones the project. If payment is a condition of reserving time, avoid beginning substantial work before the deposit has cleared.

A deposit should not be presented as a sign of distrust. It is a practical way for both parties to share the financial commitment.

Use Milestone Payments

Billing only at the end of a long project places most of the financial risk on the consultant or agency. A four-month engagement invoiced after final delivery effectively requires the supplier to fund the work until completion.

Milestone payments spread that risk more evenly. A website project might be invoiced at the following points:

When the project is booked
After the strategy is approved
When the first working version is delivered
Following final handover

Each milestone should describe an event that both sides can recognise. “Project 75% complete” is open to interpretation. “Staging website submitted for client review” is easier to verify.

For ongoing work, a monthly retainer may provide steadier cash flow. The agreement should specify whether the retainer is paid in advance or in arrears, what it includes and how work outside the agreed allowance will be charged.

Milestone billing also provides regular opportunities to identify dissatisfaction or approval problems. It is better to find out that a client has concerns after the first stage than after the entire project has been delivered.

Make Invoice Payments Easy

An accurate invoice can still be inconvenient to pay. The client may need to locate the supplier’s bank details, create a new payee, enter the amount and type the correct reference. If the invoice arrives while the recipient is travelling or between meetings, the task may be postponed.

Different clients prefer different methods. Some use bank transfers, while others prefer cards or links that take them directly to a payment screen. Providing appropriate invoice payment options can reduce manual steps and make it easier to include the correct amount and reference.

That does not mean offering every available payment method. Consultants and agencies should consider transaction values, processing fees, settlement times, client preferences and how payments will be matched with invoices in their accounting software.

The practical test is simple: once the invoice has been approved, how much effort does the client need to make before it is paid? If they must search old emails or request bank details again, the process contains unnecessary friction.

Send Accurate Invoices Promptly

Waiting several days to send an invoice delays the date on which payment can begin. Unless the contract specifies a fixed monthly billing cycle, issue the invoice as soon as the deposit, milestone or service period becomes chargeable.

Consistency matters for retainers. Sending the invoice on the same day each month helps the client fit it into an established approval routine.

The description should be specific enough for someone outside the project team to understand. “Consulting services” tells an accounts-payable employee very little. “Customer research and competitor analysis completed in September 2026” is easier to connect with an approved project.

A UK invoice should generally include a unique invoice number, supplier and customer details, the invoice date, the supply date, a description of the work, the amount owed and the payment terms. VAT invoices and invoices from particular business structures require additional information. The GOV.UK invoicing guidance explains the current requirements.

Before sending an invoice, check the:

Client’s legal name and billing address
Invoice number and date
Description of the work
Purchase-order number
VAT treatment
Total amount
Payment deadline
Payment instructions

A brief review before sending can prevent a much longer delay later.

Find the Right Payment Contact

The person who commissioned the work may approve the invoice, but that does not mean they control the payment.

Ask for the accounts-payable contact’s details at the beginning of the engagement. Find out whether invoices must be submitted to a particular email address or uploaded to a finance portal.

Where appropriate, send the invoice directly to accounts payable and copy the project contact. Include any required timesheets, delivery confirmations or purchase-order documents with the first submission.

It is also worth asking when the organisation runs supplier payments and when an approved invoice must be received. Missing a weekly cut-off by one day could delay payment for another week.

These details may feel minor compared with the work itself, but dependable cash flow is usually built on simple processes performed consistently.

Prevent Invoice Disputes

A client may question an invoice because the amount differs from the contract, a milestone has not been accepted or additional work was not authorised. These concerns should be investigated rather than treated as ordinary late payment.

Many disputes can be prevented by recording decisions in writing. When the client requests work outside the original scope, explain the cost and obtain approval before proceeding. When a milestone is delivered, ask the client to confirm that it has been accepted.

The contract should explain how invoice queries will be managed. Clients should raise concerns promptly and identify the amount being disputed. A question about one charge should not automatically prevent discussion about the undisputed balance.

Clear records protect both sides. They show the client how the amount was calculated and prevent a vague disagreement from becoming an indefinite delay.

Create a Reminder Schedule

Do not wait until an invoice is several weeks overdue before contacting the client. A short reminder before the deadline may uncover a missing approval while there is still time to correct it.

A practical sequence could be:

Three days before the deadline: Confirm that the invoice has been received
On the due date: Remind the client that payment is due
One to three days overdue: Request an expected payment date
Seven days overdue: Contact accounts payable directly
Fourteen days overdue: Escalate to the project owner or senior contact

Each reminder should include the invoice number, amount, original due date and payment instructions. Keep the language factual rather than accusatory.

For example:

I’m checking that Invoice 123 for £2,400 is scheduled for payment on 15 September. Please let me know if your finance team needs any further information from us.

Accounting software can automate routine reminders, but replies should still be monitored. If the client raises a genuine query, pause the automated sequence and address it directly.

Call When Email Stops Working

Another email may not help if several previous messages have been ignored. Call the accounts-payable contact and ask whether the invoice has been received, approved and entered into the next payment run.

The purpose of the call is to identify the obstacle. The invoice may be awaiting approval, missing a document or sitting in the wrong system.

If finance cannot resolve the issue, involve the person who commissioned the work. Explain what is outstanding, which reminders have been sent and what information you need.

Keep a record of calls, emails and promised payment dates. This history will be useful if the matter later needs to be escalated.

Pause Work When Necessary

Continuing to deliver while an invoice remains unpaid increases the amount at risk. It may also signal that the agreed payment terms are optional.

Where the contract allows it, consider pausing the next phase when an undisputed invoice becomes seriously overdue. Give reasonable notice and explain the position calmly.

For example:

Invoice 123 remains outstanding despite our previous reminders. We will need to pause the next stage of work until payment has been received. Please let us know if anything is preventing the invoice from being processed.

Pausing work should be a standard commercial boundary, not a threat made in frustration. Apply the policy consistently.

Repeated late payment should also affect future arrangements. A client that regularly exceeds its terms may need to pay a larger deposit, accept shorter terms or settle the full amount before further work begins.

Understand UK Late Payment Rules

For qualifying business-to-business debts, UK suppliers may be entitled to charge statutory interest at 8% above the Bank of England base rate. If the contract already specifies a different interest arrangement, the contractual provisions may apply instead.

Businesses may also be entitled to fixed debt-recovery compensation:

£40 for debts below £1,000
£70 for debts from £1,000 to £9,999.99
£100 for debts of £10,000 or more

The GOV.UK late commercial payment guidance explains when a payment becomes late and how interest and recovery costs may be claimed.

The Small Business Commissioner also provides guidance on payment terms and disputes involving small suppliers and larger private-sector businesses.

These rights can be useful when an accepted invoice remains unpaid, but they should be applied carefully. A genuinely disputed invoice, an insolvent client or an international contract may require a different approach. Consider obtaining independent legal advice when the debt is significant.

Review Your Payment Process

One late invoice may be an isolated mistake. Repeated delays usually indicate a wider problem with the client or the payment process.

Monitor how long it takes to issue an invoice after completing work, the percentage paid by the due date and the clients that regularly exceed their terms. Record why invoices are rejected and how long disputes take to resolve.

These patterns can reveal where changes are needed. Frequent missing purchase orders suggest a weakness in client onboarding. Delayed invoicing points to an internal process problem. Payments without recognisable references may mean the available payment instructions need to be improved.

The objective is not to become more persistent at chasing invoices. It is to reduce how often chasing is required.

How to Get Paid on Time Consistently

Late payments cannot always be prevented. A client may experience financial difficulties, an invoice may be genuinely disputed or an internal approval may take longer than expected.

However, consultants and agencies can remove many avoidable delays by checking clients carefully, agreeing clear payment terms and invoicing throughout the project. Accurate invoices, convenient payment methods and consistent reminders make the remaining process easier to manage.

Getting paid on time should not depend on remembering to send an uncomfortable email. It should be the expected result of a payment process that both the supplier and the client understand from the beginning.