MonolithTechnologies Limited
Engineering

Webhooks done right: a reliability checklist for payment integrations

A practical checklist for receiving payment webhooks safely: verify signatures, acknowledge fast, handle duplicates, confirm with the source of truth and plan for failure.

Abraham Olagunju

27 Oct 2026 · 2 min read · 1 views

Webhooks done right: a reliability checklist for payment integrations

Payment providers tell your system what happened through webhooks: a charge succeeded, a transfer failed, a refund was processed. Most integrations treat the webhook endpoint as an afterthought, and that is where money-related bugs hide. This is the checklist we use when we connect a payment provider to a product.

1. Verify every request

Anyone can send a POST request to a public URL. Before you trust a payload, verify the signature the provider sends with it, using the raw request body and a secret that lives in your server's environment, never in client code. Reject anything that fails, and compare signatures in constant time.

2. Acknowledge fast, process later

Providers expect a quick 2xx response and will retry if they do not get one. Do the minimum inside the request: verify, store the event, return 200. Then process it from a queue or background job. Slow handlers cause timeouts, and timeouts cause duplicate deliveries.

3. Assume duplicates and disorder

Webhooks are delivered at least once, not exactly once, and not always in order. Make handlers idempotent:

  • Store the provider's event or reference ID and ignore ones you have already processed.

  • Make state changes conditional, for example only mark an order paid if it is still pending.

  • Never assume a "failed" event arrives before a "succeeded" one for the same reference.

4. Confirm with the source of truth

For anything that moves money or unlocks a product, treat the webhook as a signal and confirm the final state by calling the provider's verify endpoint with the transaction reference. Check the amount, the currency and the status against what you expected, not only that a payment exists.

5. Log everything, and keep the raw payload

Store the raw event body, headers, receive time and the outcome of processing. When a customer says they paid and did not get their order, this log is how you answer in minutes instead of days. It also lets you replay events after you fix a bug.

6. Plan for failure

  • Alert when events fail processing repeatedly, not just when the server is down.

  • Run a reconciliation job that compares your records with the provider's, so missed webhooks are caught the same day.

  • Test with the provider's sandbox, including failed payments and retries.

0 Comments

Loading comments…

Related articles