A webhook is a notification the payment service sends to your site's address whenever a payment status changes. It — not the buyer returning to a thank-you page — should be treated as the source of truth: it is the only way the store reliably learns about a payment.
Why the redirect is not enough
A buyer can close the tab right after paying, lose connectivity or never wait for the redirect. The money is still taken, but the store never finds out — the order sits in "awaiting payment" and someone has to sort it out by hand.
A webhook reaches your server regardless of what the buyer does.
What your handler must do
- Accept the request and answer 200 immediately — otherwise the service treats delivery as failed.
- Find the order by the identifier you passed when creating the payment.
- Verify the request signature before changing anything in the database.
- Update the order status and store the payment id for reconciliation.
Common mistakes
- The address sits behind auth or a firewall — notifications never arrive.
- The handler returns 500 or times out — usually heavy logic inside; move that to a background job.
- No signature check — the endpoint will accept whatever arrives.
- Processing the same notification twice — it can be delivered more than once, so the handler must cope.
Integration details are on the payment API page.
