Booking Lifecycle Event Model

A booking lifecycle model should preserve which events occurred, in what order and from which evidence current state was derived, rather than reducing the reservation to one mutable status field.

Production scenario

A create request times out while the supplier may have created the booking. A CONFIRMED webhook later arrives, followed by cancellation and refund events. One status field loses the audit trail.

Architecture flow

Booking Attempt
 -> CREATE_REQUESTED
 -> provider call
 -> CREATED / UNKNOWN / FAILED
 -> CONFIRMED
 -> MODIFIED?
 -> CANCEL_REQUESTED?
 -> CANCELLED?
 -> REFUND/SETTLEMENT?
 -> RECONCILED

Key entities

Use Booking, BookingAttempt, BookingEvent, ProviderBookingReference, PaymentReference and ReconciliationRecord.

Event shape

A useful event stores event ID, booking ID, event type, provider, provider reference, occurred/received timestamps and source such as API response, webhook or reconciliation.

State derivation

Materialize current booking state from event history. Not every incoming event should be allowed to produce every transition.

Out-of-order events require explicit handling.

Idempotency

Webhook delivery can repeat. Deduplicate using provider event IDs or deterministic event keys before applying state changes.

Unknown state

UNKNOWN should be a first-class state after ambiguous timeouts. Marking it FAILED too early can cause duplicate bookings.

Resolve UNKNOWN through lookup and reconciliation.

Separate payment lifecycle

Payment authorization does not prove booking confirmation. Maintain separate booking and payment state machines and reconcile them explicitly.

Failure modes

Common failures include duplicate webhooks, out-of-order events, provider-reference changes, payment/booking divergence, premature cancellation state and duplicate creates after retry.

Concurrency

Protect state materialization with event versions, sequences or optimistic concurrency. Parallel consumers must not apply transitions nondeterministically.

Observability

Track unknown-booking age, duplicate/out-of-order events, booking/payment divergence, reconciliation latency and invalid transitions.

Alternatives

For a simple low-volume single-provider system, an event table plus materialized status may be enough. Full event sourcing is justified only when replay/audit requirements warrant the complexity.

Production checklist

Use immutable events, explicit transition rules, idempotency, ordering/version strategy, UNKNOWN state, separate payment lifecycle, reconciliation jobs, audit trails and replay tooling.