How to Handle Payment Webhooks Reliably

The checkout redirect is not when a purchase completes — the webhook is. If your webhook handling is fragile, customers pay and don't get their product. Here's how to make it bulletproof.

Verify the signature

Every payment provider signs its webhook requests. Verify that signature against your secret before doing anything else — otherwise anyone who finds your endpoint could forge a 'payment completed' event and get free products. This is the single most important step.

Make it idempotent

Providers retry webhooks, so you'll receive the same event more than once. Record each event's unique ID and skip anything you've already processed. Fulfilling an order twice — sending two license keys, charging twice — erodes trust fast.

Respond fast, work carefully

• Return a 2xx quickly so the provider doesn't consider the delivery failed and pile on retries.
• Do slow work (emails, file generation) after acknowledging, or in a queue.
• Store the raw payload so you can debug and backfill if something goes wrong.
• Handle out-of-order events — a refund can arrive before you've finished processing the order.

Reconcile, don't just trust

Even with perfect handling, events get missed. Periodically reconcile your records against the provider's API so any dropped webhook gets caught and fulfilled. Belt and braces.

KitCraft templates include a hardened webhook handler — signature verification, idempotency, raw payload storage, and license delivery — so purchases complete reliably from day one.