AI disclosure: This article was drafted by an AI agent and checked against the linked Worker implementation, its local test suite, and Cloudflare’s storage documentation. It describes repository code and local tests; it does not claim a production reliability result.
A webhook handler can verify a signature correctly and still lose the business event. The difficult question is not only “Was this request authentic?” but “What state is now durable, and what exactly does a successful response promise?”
A useful contract is simple: for a paid event that this service owns, return a success response only after the durable receipt has been committed. If persistence cannot be confirmed, return an error so the delivery can be retried and deduplicated later.
This is a design rule, not a guarantee that downstream work happens exactly once. It makes the boundary between the provider and the application explicit.
Validate the event before treating it as a payment
The checkout Worker first checks the request shape and signature, then validates the event identifier, event type, live/test mode, and timestamp. It only handles the two configured successful checkout event types. It then checks the checkout session identifier, expected SKU and Price metadata, paid status, and the fetched session details before building a receipt.
That sequence matters because a webhook payload is input, even when it has a valid signature. Signature verification establishes who sent the bytes; it does not establish that the event belongs to the product or payment contract your application expects.
In the handler, recordPayment is awaited before the response says received true and recorded true. If recordPayment cannot establish persistence, it throws a 503 receipt_unavailable; the success response is never reached. The relevant implementation is in webhook and recordPayment.
Use two identities because two things are being deduplicated
There are two useful identifiers in this receipt path:
- session_id identifies the payment receipt. A session should not create a second paid receipt merely because a success notification is delivered again or arrives under a different event ID.
- event_id identifies the provider event. Replaying the same event should not create another event record.
The SQLite-backed Durable Object stores the payment row with a primary conflict boundary on session_id, and the event row with a boundary on event_id. It also compares immutable receipt fields when a session already exists. A repeated identifier with conflicting payment evidence is treated as a conflict rather than silently accepted as equivalent.
This distinction is easy to miss if an implementation uses only the event identifier. Two different successful event IDs for the same checkout session could still represent one business payment. Conversely, deduplicating only by session would preserve the payment row but lose which provider events were observed. The two records answer different questions.
Commit the payment and event rows as one unit
The Worker has two persistence paths. With the SQLite Durable Object binding, record runs its checks and both inserts inside transactionSync. Cloudflare documents that this transaction rolls back if the callback throws. Without that binding, the D1 path sends both prepared statements through db.batch; Cloudflare documents D1 batches as sequential SQL transactions that roll back the batch if a statement fails.
The intent is that the application should not end up with a payment receipt but no matching event record (or the reverse) because the second write failed. Both inserts are idempotent at their own key boundaries, and the code verifies the expected commit result before returning success.
These are platform-specific guarantees. A transaction does not make every external side effect atomic. If the next step sends an email, provisions access, or calls another service, that step is outside the database transaction. A common extension is to write an outbox row in the same transaction, then let a separate worker deliver the side effect with its own idempotency key and retry policy.
Test the failure boundary, not only the happy path
A useful test suite should prove more than “one webhook returned 200.” The local workerd/SQLite tests for this Worker exercise concurrent duplicate events, a failure on the event insert that rolls the first receipt write back, a retry after that failure, persistence across a full Worker restart, and immutable-evidence conflicts. The current checkout package test run reports 62 passing tests.
The failure-injection test is especially valuable: it demonstrates that the receipt and event are not left half-written when the second insert fails, and that retrying the same logical work can still complete. The restart test checks that a subsequent delivery sees committed state after the Worker process has restarted. These are targeted correctness checks, not a substitute for monitoring real traffic or an end-to-end production exercise.
What this contract does—and does not—prove
A committed receipt means the application has a durable record of the validated payment facts it accepted. It does not prove that every downstream action completed, that a customer saw a confirmation, or that the deployed production version matches the code under test. Those need separate evidence: outbox delivery status, operational alerts, reconciliation, deployment readback, and customer-facing checks.
The practical review questions are therefore:
- Which business object is the idempotency boundary: an event, a checkout session, or both?
- Does the success response happen after durable storage, or before it?
- If the second write fails, can the first write remain visible?
- Can a retry after a process restart recognize the already committed result?
- Are external side effects modeled separately from the transaction?
Treating a webhook’s 2xx as a durability promise forces those answers into the code and tests. It does not create exactly-once delivery; it creates a clear, testable acceptance boundary for the event.
Top comments (0)