Return the 2xx only after the event is durably stored, not after the ledger effect. Make the ledger write idempotent and process asynchronously. Three tests settle it before go-live: crash after 2xx, duplicate delivery, and concurrent processing under your database's actual isolation level.
The decision, answered
Return the 2xx only after the event is durably stored, and let the ledger effect happen later in its own idempotent transaction: the acknowledgement commits receipt, not the business outcome. Three tests settle this before go-live: a crash after the 2xx, a duplicate delivery, and concurrent processing under your database's actual isolation level. Widen the 2xx to cover the ledger effect only after a fourth test: a crash after commit but before the 2xx, followed by a replayed delivery.
What the vendor guidance actually says
Adyen Docs describes a webhook as a lightweight mechanism where the vendor pushes event-driven messages using HTTP POST calls to an endpoint you define, and states that you need to accept webhooks with a 2xx HTTP status code, store the message, and process the contents of the message. Adyen Docs also states that webhook messages contain a snapshot of the resource, so your system can update its state accordingly, and that many integration flows are asynchronous, meaning the final status of a resource is not known immediately after an API request.
The Amazon Builders' Library article on idempotent APIs states that retrying a service call as mitigation for a transient fault rests on a simplifying assumption: that the operation can be retried without side effects, so the result of the call happens only once even if the call is made multiple times in a retry loop. It also states that some AWS SDK implementations automatically retry requests that fail due to network IO issues, server-side fault, or service rate limiting. That statement describes client-side retries against AWS services. Whether your webhook vendor redelivers after a 2xx is a question we propose you put to the vendor in writing; it is a diligence item, not something the AWS article settles for your integration.
The 2xx is a transport-level signal. What it commits inside your system is a decision you own, and the rest of this guide is a proposed method for making it deliberately.
The failure mode: two commit points, one acknowledgement
There are two durable commit points in this integration: the event record and the ledger transaction. The 2xx is a third, weaker signal that can be aligned with either one. The failure mode is letting it float between them.
Two points follow from the sources, and we label both as our inferences, not vendor statements. First, a receiver that returns 2xx before durably storing the event opens a crash window in which the vendor may treat delivery as accepted while your firm holds no record of the event; this follows from Adyen's accept-store-process sequence. Whether the vendor covers that window with redelivery is unresolved until the vendor confirms its policy, so treat it as an open question in your inventory. Second, if the same webhook is processed twice and the ledger write is not idempotent, the business effect can occur twice; the AWS retry-safety premise makes duplicate delivery a business-effect risk whenever it happens, not only a transport inconvenience.
Step 1: the commit-point inventory
We propose that, before go-live, you write a one-page inventory naming three things: what the 2xx commits, what the durable event row commits, and what the ledger transaction commits, with a named owner for each. The engineering owner of the integration writes it; the operations or finance-system owner signs off on what the ledger transaction is allowed to mean, because a double-posted invoice or a mispriced balance is their problem, not just yours. Confirm who actually owns the ledger write in your firm rather than assuming the role.
The evidence that settles this step is the inventory itself, reviewed against the vendor's documented delivery behavior. Adyen Docs supports an inbox-style event record through its guidance to store the message before processing; the schema, retention period and processing guarantees are design choices you document yourself, since they are yours to set.
Step 2: the crash test
We propose a test that kills the receiver process at each point in the sequence: immediately after the 2xx is sent but before the event store commit, and immediately after the event store commit but before the ledger write. The evidence that settles it is what you can reconstruct afterward. If the process dies after the 2xx and before the store, you should be able to answer two questions: does the vendor redeliver, and can you reconcile the missing event from the vendor's side? If you cannot answer either, the 2xx is committing something you cannot recover, and it must move later, to after the durable store.
The integration engineer owns the kill switch and the test script. The sign-off criterion is written, not observed: a post-crash state where either the event row exists or the vendor's redelivery covers the gap, with no silent loss.
Step 3: the duplicate delivery test
We propose replaying the identical webhook payload twice through the full path, after the event store, and comparing the ledger state. The evidence that settles it is the ledger delta: zero for a pure duplicate, one business effect total. The Amazon Builders' Library framing gives the acceptance criterion: the result happens only once even if the call is made multiple times. If the second delivery produces a second invoice, a second balance movement, or a second status transition, the ledger write is not idempotent, and the 2xx must not imply the ledger effect.
The owner here is whoever owns the ledger write in your firm, working with the engineer who wrote the handler. The condition that changes the recommendation: if you cannot make the ledger write idempotent, keep the 2xx tied only to durable event receipt and process asynchronously, so the acknowledgement never implies the ledger effect.
Step 4: the concurrency test under your real isolation level
We propose treating concurrency as a live possibility and testing it as a precaution: process two deliveries of the same event concurrently and inspect what the database actually does. Duplicate deliveries may not arrive serially, and the cost of finding out in production is a ledger you cannot explain.
PostgreSQL documentation states that Read Committed is the default isolation level, that a SELECT query sees only data committed before the query began, and that two successive SELECT commands can see different data within a single transaction if other transactions commit after the first SELECT starts and before the second starts. The inference we draw, labeled as such: a processor that reads a balance or status in one statement and writes in a later statement can act on a changed view if another transaction commits between them. This follows from the documented visibility rule; it is not a claim that every webhook processor behaves this way, and you should verify it in your own code path.
PostgreSQL documentation also states that UPDATE, DELETE, INSERT and MERGE acquire ROW EXCLUSIVE lock mode on the target table, that two transactions cannot hold locks of conflicting modes on the same table at the same time, and that the pg_locks system view lists currently outstanding locks. We propose using pg_locks during the concurrent test to see whether your processor holds conflicting table-level locks, and treating the result as a hypothesis about your system rather than a guarantee. If you need stronger guarantees, the documentation states that PostgreSQL's Repeatable Read implementation does not allow phantom reads, and that Serializable does not allow dirty read, nonrepeatable read, phantom read, or serialization anomaly. Those are options to evaluate, not defaults; Read Committed is the default, so test under what you actually run.
When the recommendation changes
The receipt-only recommendation is conservative, and it changes only under conditions you have tested. If the event store and the ledger write live in the same database and can run in a single transaction, that alone is not sufficient to widen the 2xx. Consider the crash after commit but before the 2xx is sent: both effects are already committed, and if the vendor redelivers, the replay can duplicate the ledger effect. Widening the 2xx therefore requires three things together: the single-transaction design, an idempotency or dedupe mechanism keyed on the event so a replayed delivery produces no second effect, and a written vendor redelivery policy you obtain from the vendor. The fourth test settles it: crash after commit but before the 2xx, then replay the delivery, and confirm the ledger delta is one effect. If any of those conditions fails, the 2xx stays tied to durable receipt only. What does not change: the 2xx must commit something you can either recover or prove happened exactly once.
Checks
- Write the commit-point inventory naming what the 2xx, the event row and the ledger transaction each commit, with an owner per line.
- Kill the receiver after 2xx but before the event store commit, and confirm you can recover the event from redelivery or vendor-side reconciliation.
- Replay the identical webhook payload twice and verify the ledger delta is one business effect, not two.
- Process two deliveries concurrently under the database's actual isolation level and inspect pg_locks or your database's equivalent for conflicting locks.
- Confirm the vendor's redelivery policy after a 2xx in writing before go-live.
- If widening the 2xx to cover the ledger effect, run the post-commit, pre-2xx crash test with a replayed delivery and verify the dedupe mechanism holds.
- If the ledger write cannot be made idempotent, change the design so the 2xx commits durable receipt only and processing is asynchronous.
Questions
Does the vendor redeliver a webhook after receiving a 2xx?
The Amazon Builders' Library states that some AWS SDK implementations automatically retry requests that fail due to network IO issues, server-side fault, or service rate limiting; that describes AWS clients calling AWS services. We propose you treat webhook redelivery after a successful 2xx as possible until your vendor confirms a policy in writing, and design the duplicate test accordingly.
Should we process the webhook inline before returning 2xx?
Adyen Docs states the sequence as accept with 2xx, store the message, and process the contents, which supports storing first. Whether processing completes before or after the 2xx is your design decision. The crash and duplicate tests settle it: inline processing is acceptable only if a crash between 2xx and completion is recoverable and a retry produces one business effect.
Our ledger is not PostgreSQL. Does the concurrency test still apply?
The PostgreSQL citations describe PostgreSQL, not every database. Run the same concurrent-delivery test against your actual database and read its own documentation for the default isolation level and lock behavior. The test method transfers; the documented specifics do not.
