Short answer
Treat a webhook as a retryable event rather than a one-time signal. The system must accept duplicates safely, survive temporary downtime and avoid releasing value twice.
- Record the event before heavy processing and respond quickly.
- Validate authenticity using the current documentation.
- Allow only valid status transitions.
- Keep an audit trail for investigation and reconciliation.
Why notifications are repeated
A provider may retry delivery when it does not receive a timely successful response. Networks can delay requests, and events from different attempts for one order may arrive close together. These are normal distributed-system conditions.
The handler must not assume each notification is unique or delivered exactly once. Enforce uniqueness through an event identifier or a stable combination of available fields.
How to structure the handler
First validate technical correctness and authenticity, then find the payment, compare the expected amount and store the event. Updating the order and releasing the result should be atomic or delegated through a reliable queue.
Respond quickly. Send email, generate documents and perform other long-running work asynchronously after the status is recorded.
- validate under the documentation;
- find the payment by identifier;
- check amount and currency;
- store the event idempotently;
- perform the business action once.
Design the status model
Not all statuses have the same meaning. A technical created state is not payment, and a refund must not move an order back to paid. Define terminal and intermediate states and their permitted transitions.
For an unknown value, store the event for review and avoid a financial action until clarified. Do not hardcode strings without checking the current documentation.
Recover from failures
Add a process that rechecks payments remaining in an intermediate state for too long. Compare them with the API and transaction register and log the final resolution.
Alerts should cover signature failures, a growing queue, repeated events and reconciliation differences. This detects issues before the customer contacts support.
Questions and answers
Should the webhook response wait for full order processing?
Record the event reliably and respond quickly; continue heavy work through a queue.
Can the browser return status be trusted?
No. A verified server channel or status query confirms the financial result.
What should happen with an unknown status?
Store the event, avoid irreversible action and consult the current documentation.
Sources and policies
We use official payment-system information and WHITECAPITAL policies. Contractual documents prevail for an individual merchant setup.
This material is for operational orientation and is not a promise of approval, universal method availability, a fixed fee or settlement timing.