Verify and save before acknowledging
A webhook is a notification a service sends to an endpoint when something happens. Adyen’s handling documentation describes a sequence of verification, durable storage, acknowledgment and processing. Follow the requirements for the provider and webhook type you use.
- Verify the notification using the provider’s documented method. A signature may cover the raw request or particular fields. Use a supported validation library where available, and keep test and live endpoint secrets distinct. Valid JSON alone does not authenticate the sender.
- Store the verified event durably. An event held only in memory can disappear on a restart, so it is not enough to justify acknowledging successful receipt.
- Return the response the provider requires within its documented deadline. The acknowledgment confirms receipt; it does not confirm that the order was paid or fulfilled.
- Process the event after acceptance. Keep lengthy order or fulfillment work out of the acknowledgment path.
Match the event to the order
Check the expected account, test or live environment, payment object and order. Then check the amount, currency and payment state before deciding what action is due.
Delivery order may differ from event order. Stripe, for example, does not guarantee event ordering. Follow the provider’s event semantics and retrieve the current payment object when needed. An older notification arriving late should not overwrite a more current state.
Use a documented event identity to recognize repeat deliveries. Two different event IDs can still concern the same payment and business action. Keep the event-handling record and the business rule that determines whether that action has already been completed.
One order, one shipment
Suppose order 575 has one shipment due after its payment reaches the required state. The provider sends the notification again because it did not receive the first acknowledgment.
The second HTTP request must not create a second shipment. The receiver needs to recognize the repeated event and continue from its durable record.
Test what happens on either side of storage. If processing stops before the event is saved, the receiver must not claim successful receipt; the provider’s documented retry behavior applies. If it stops after storage but before the sender receives the acknowledgment, the repeated event should lead back to the saved record.
A different problem arises if the receiver requests a shipment and stops before recording completion. Before sending again, reconcile the result in the fulfillment system or use that system’s idempotent operation where supported. A local “processed” flag alone cannot close the gap between two systems.
Also test an older event arriving after a newer one. Apply valid state transitions rather than trusting arrival order. These checks aim to complete the intended action once despite repeated delivery; they do not make the network deliver events exactly once.
Make failed processing recoverable
Use the provider’s approved test facilities for duplicate, delayed, invalid-signature and interrupted-processing cases. Monitor how long events remain unprocessed, failed verification and repeated worker failures. An endpoint’s HTTP success rate alone does not show whether the business work finished.
Keep enough non-secret references to investigate the event and its order. Do not log signing secrets or unnecessary payment data. Record who may replay an event, how they check whether its action already completed and when a case needs manual review.
Provider delivery retries and your processing retries are separate. After the receiver accepts an event, a failed internal job may need your recovery process even if the provider considers delivery successful. Follow your payment provider’s instructions for configuring the receiving endpoint and handling delivery retries.