One local database transactionOriginal eventSame eventUniqueclaimEffectResultCommit all three, or commit none.A later duplicate reads the stored outcome instead of applying the effect again.
The claim, mutation and recorded outcome share one transaction boundary in this example. Synthetic design, not a vendor protocol. Scroll the diagram horizontally for detail.

An idempotency key is an input to a protocol, not a force field around a function. A receiver must decide which operation the key identifies, how it claims that operation, what it remembers and what a later caller receives. The useful question is not whether a request has a key. It is whether two arrivals can cross the mutation boundary twice.

This example updates a synthetic session-completion counter. We assume one relational database can atomically store a deduplication record and the counter change. The browser lab simplifies that transaction to sequential in-memory state. It helps explain repeated effects, but it cannot prove that a production database implementation handles concurrent writes correctly.

Define the intended effect

For this exercise, one logical completion event increments a counter once. Logging each attempt is allowed; incrementing the business counter twice is not. The distinction matters because an idempotent operation can still produce multiple log records or responses. HTTP’s definition concerns the intended effect, rather than identical response bytes or the absence of every secondary activity. See RFC 9110, section 9.2.2.

A robust identity includes a namespace. Our example uses the receiving tenant, operation kind and producer event ID. Two unrelated producers may both call an event “17”; two different operations may legitimately share a business object ID. Neither should collide simply because the application stored an unscoped string.

The same key with a changed payload is a separate problem. Store a stable digest of the fields that define the operation, or another validated representation of intent. Compare it on reuse. Reject an incompatible request rather than returning an earlier success for a different operation. Avoid hashing arbitrary JSON text unless field ordering and representation are deliberately normalized.

Put the claim beside the mutation

Consider the tempting implementation: look up the key, return if found, otherwise update the counter and insert the key. Two workers can both observe absence before either writes. Both then increment. Adding a cache does not remove this race; it merely moves the shared decision somewhere else.

In our proposed database design, a unique constraint protects the scoped key. Within one transaction, a worker claims the key, performs the counter update and stores a replayable result. Another worker attempting the same claim either waits or loses the uniqueness race, depending on the database’s behavior. It then reads the committed result according to the chosen isolation policy.

BEGIN
  claim (tenant, operation_kind, event_id) uniquely
  compare the stored intent if this is a replay
  apply the completion effect if this is a new claim
  record the stable outcome
COMMIT
acknowledge the recorded outcome

This is pseudocode, not executable SQL. A real implementation must define conflict handling, transaction isolation, lock timeouts and what a worker returns while another claim is still pending. The critical feature is that the effect cannot commit without the identity record, or the identity record without the corresponding effect.

Crash at the awkward moment

Suppose the worker commits both records, then crashes before responding. A retry carries the same identity. The receiver finds the committed result and acknowledges it without incrementing again. A new response may have a different delivery timestamp, but it still describes the same business outcome.

Now crash before the transaction commits. Both changes should roll back together. The retry may safely attempt the operation again. A test that only checks ordinary duplicate requests will not detect a design that writes the key before the mutation in a separate transaction; that design can remember a success that never happened.

{
  "example": true,
  "event_id": "completion-example-017",
  "operation": "session_completed",
  "state": "committed",
  "result_uri": "https://example.invalid/outcomes/example-017"
}

If the effect is a remote call, the single-database assumption no longer holds. An outbox can make the intent to call durable, but dispatch may repeat. The remote receiver still needs repeat-safe semantics or a reconciliation path. Do not promote a local transaction guarantee into a claim about every downstream system.

Choose what memory costs

Keeping deduplication records indefinitely simplifies old-event handling but grows storage and creates retention questions. Expiring them bounds storage but allows a sufficiently late replay to appear new. Choose the lifetime together with the producer’s retry window, manual replay policy and the period during which a duplicate effect would still be harmful.

For our completion counter, imagine a seven-day automatic retry window and a thirty-day operator replay policy. A retention period covering only seven days leaves an obvious operational gap. Those numbers are illustrative, not recommended universal defaults. The contract must also say what happens after expiry: reject an old event, reconcile it, or intentionally accept the duplicate risk.

Store the smallest useful result. Replaying a full response body may retain sensitive fields or expired launch capabilities. A stable operation status and a safe result reference can be sufficient. If a client needs a fresh capability, treat its issuance separately from replaying the original business effect.

Inspect the lab trace

In Callback Lab, choose at-least-once delivery, three duplicates, no injected failure and a 1000ms timeout. With idempotency enabled, four envelopes arrive, one commits and three are ignored. With it disabled, four effects occur. The envelope count did not change; the processing policy did.

Next reduce timeout to 200ms and set duplicates to zero. The first effect commits at 400ms, after the acknowledgement deadline. Idempotency lets the next attempt return the recorded outcome in 50ms. This demonstrates why retrying and deduplicating work together. It does not model simultaneous claims, storage outages or retention expiry.

Test a claim under contention

Use a barrier to release two local test workers with the same scoped key at the same instant. Assert exactly one committed counter increment and two compatible outcomes. Measure committed state directly; two successful HTTP responses are not proof that only one mutation occurred.

Repeat with a different payload under the same key and require a conflict. Repeat with the same event ID in a different tenant and verify isolation. Crash a worker before commit, after commit and before response serialization. Finally, expire the identity record and replay the event to verify the documented expiry policy.

The phrase “exactly once” is only meaningful with a named boundary, failure model and retention period. In this manual we claim one intended effect within our synthetic model’s lifetime. For delivery behavior read callbacks and retries; for inspecting attempts without confusing them with effects, read observability.