What is a webhook and how payment notifications work

A webhook is a reverse API call. Instead of your server repeatedly asking “has the order been paid yet?”, the payment service sends an HTTP POST to a URL you configured as soon as something happens. The body usually contains the event type (payment paid, underpaid, expired, payout sent) and the object’s data. Your server processes it and replies with a 2xx status.

For payments, webhooks are how your backend learns that it can ship an order, activate a subscription or credit a balance. The payment page shows the customer the status, but the trusted signal for your system should be the webhook, verified on your side, or a direct API request to the gateway.

Webhooks are delivered over the open internet, so they must be protected and handled robustly. A good provider signs every request (for example with HMAC), retries delivery when your server is down or returns an error, and keeps a log of attempts. Your handler, in turn, must verify the signature, be idempotent, because the same event can arrive more than once, and respond quickly, deferring heavy work to a queue.

Common mistakes: trusting a webhook without checking its signature; marking an order as paid twice because a retry arrived; doing slow work before replying, which causes timeouts and more retries; returning 200 even when processing failed, so the event is lost; and relying on the order of events, which is not guaranteed.

Moonvex signs webhooks with HMAC in the Moonvex-Signature header, retries delivery for up to three days and keeps a delivery log, so you can see every attempt. For Node.js there is the official SDK @moonvex/node.

Checklist for a webhook handler

• verify the signature against the raw request body
• deduplicate events by their ID
• reply with 2xx quickly and process asynchronously
• return an error status if processing failed, so the event is retried
• don’t assume events arrive in order