Why payments need webhooks
Why crypto payments need one
Because settlement is asynchronous and slow relative to a web request.
A card authorisation returns an answer in a second, so the merchant can hold the HTTP request open and respond to the customer immediately. A crypto payment waits for the network: seconds on Solana, minutes on Ethereum, up to an hour on Bitcoin with several confirmations.
Nothing can hold a request open that long. So the checkout tells the customer the payment is being confirmed, and the gateway sends a webhook when it is, at which point your system fulfils the order.
What a payment webhook contains
Five things, and each is needed for a different reason.
The order reference, so you know which order this concerns. The status, which is the point of the message. The amount and asset actually received, which lets you detect underpayment. The transaction hash, which is your audit record. And the fiat equivalent at receipt, which is the figure your accounting needs.
How to handle them correctly
Signature verification is not optional
The most important paragraph here.
A webhook endpoint is a public URL, and anyone who finds it can send it a message claiming a payment succeeded. An endpoint that credits orders based on what arrives at it will give away goods to whoever discovers the address.
Providers sign each webhook, usually with an HMAC over the payload using a shared secret. Your endpoint recomputes the signature and rejects anything that does not match. Skipping this step is the single most common security failure in payment integrations, and it is worse than not integrating at all.
The same applies in reverse: never credit an order based on the customer’s browser being redirected to a success page. The browser is under the customer’s control. The webhook is not.
Duplicates are normal
Webhooks are delivered at least once, not exactly once.
A provider that sends a message and does not receive a confirmation retries, and the original may have arrived anyway. Network conditions produce the same result. This means your system will receive the same notification twice, and treating that as a bug leads to double-fulfilled orders.
The fix is idempotency: record which notification identifiers you have processed and ignore repeats. Make fulfilment safe to attempt twice. This is standard practice in payment integrations and it applies identically to mass payouts, where a duplicate run pays everybody twice with no way to recall it.
Retries and what to return
Return a 200 status quickly, before doing the slow work.
Providers retry on any non-success response, usually with increasing intervals over hours or days. An endpoint that does its processing before responding risks timing out, triggering a retry, and processing the same event again.
Acknowledge first, queue the work, process asynchronously.