A blockchain event consumer must recover observations missed during an outage and reconcile recent history that changes after a reorg. Delivery handling alone cannot establish canonical application state. This guide covers replay, backfills and reversible updates. Use the receiver guide for authentication, durable receipt and acknowledgements.
Define a durable processing cursor
A cursor should represent work fully committed to the application’s storage. Record the network and the provider’s documented stream position, and retain block context where available. Advance the cursor together with the associated event updates so a process restart cannot skip work that was fetched but not stored. Keep a separate record of unresolved ranges or observations.
Detect a gap without assuming delivery order
Use the service’s documented position or sequence model when available. A delayed webhook is not necessarily a missing block, and a block without matching events may generate no notification. Monitor the last verified progress and compare it with the subscription’s expected behavior. If the service lacks a gap indicator, plan an independent reconciliation job.
Choose replay or bounded RPC backfill
Confirm the event service’s replay API, retention and coverage. If the missing range is not replayable, use supported RPC reads or another documented data source to reconstruct it. For contract logs, limit ranges and filters to the required events. Preserve the distinction between direct observations and a normalized provider payload so the reconstructed data remains explainable.
Overlap recovery with the live consumer
Resume from before the last verified point and let recovery overlap live ingestion. Deduplicate observations using identifiers appropriate to the chain and event type. Keep delivery deduplication separate from chain-event identity. A bounded overlap is safer than trying to switch historical and live processing at one exact moment.
Reverse provisional effects when history changes
Store recent block hashes and enough source data to undo or rebuild provisional updates. If the saved block is no longer canonical, find a common ancestor and replay the affected range. Keep irreversible business actions behind an appropriate confirmation and authorization policy. A notification of activity should not permanently finalize an order merely because it arrived first.
Reconcile derived state after recovery
Compare a sample of stored events with chain receipts or equivalent evidence at the same block. Rebuild important derived totals from source records and check the saved cursor. Document unsupported ranges and unresolved differences. Test restarts, duplicated recovery data and a changed recent block before depending on the event stream for production state.
Frequently Asked Questions
Can webhooks guarantee that my consumer never misses an event?
Your design should follow the documented delivery and replay contract and still preserve a recovery path. Confirm retention, gap detection and unsupported periods rather than assuming unlimited replay.
Why replay an overlapping range?
It closes uncertainty around the transition to live processing or a saved cursor. Durable event identity and idempotent updates let the consumer safely read an overlap.
Is duplicate delivery the same as a reorg?
No. Duplicate delivery repeats a notification. A reorg changes which chain observations are canonical and may require reversing provisional application effects.