Transactional outbox delivery
Reconcile the outbox with the consumer outcome
An outbox row marked published does not prove the business effect completed. Trace the event through publication, delivery and consumer state before replaying it.
In this article
Locate the event from the business report
Start with the affected order or other aggregate and identify the committed event. Confirm its type, version and intended consumer outcome.
Inspect outbox status, publication attempts and broker identifiers. A pending row may indicate no confirmed publish, while a published row shifts the investigation towards delivery or consumption. Preserve uncertainty if the publisher lost its response.
Do not edit the event payload to match current state before understanding the original transition. An event describes a particular committed change, not an arbitrary snapshot an operator can rewrite.
Follow the stable event identifier
Find the consumer's processing record and target effect. Determine whether it rejected the schema, failed a business rule, retried a dependency or completed successfully.
If the consumer completed but the user-facing read model is stale, replaying the event may not address the failed layer. Trace the final projection or cache separately.
Keep diagnostic details bounded. Event payloads can contain business or personal information, so use identifiers for coordination where possible.
Choose a recovery action with duplicate handling known
For an unpublished event, use the supported publisher retry or claim recovery. For a delivered event whose consumer failed, use the consumer's retry or replay process. Preserve the original identifier in both cases.
Before replaying, confirm the consumer's deduplication and side-effect rules. A processed marker may intentionally suppress a duplicate, which means a separate repair operation could be needed for an incomplete external effect.
Do not delete a processed marker merely to force work through without understanding what already happened. That can turn a missing read-model update into a duplicate charge, notification or task.
Verify the business result
Inspect the target state and record the recovery operation. Confirm delayed deliveries cannot undo or repeat the correction under the event-ordering policy.
Record the failed stage, event age and root cause. Add a regression for the mechanism, such as a partial batch failure or consumer schema mismatch.
The incident is closed when the intended business outcome is established and the event trail explains it. Clearing an outbox row or reducing queue depth alone is not proof of recovery.
Primary sources
AWS: transactional outbox patternAWS Builders' Library: idempotent APIsReferences checked 11 September 2026.