Skip to main content

​
Overview

Blockchain data is produced by distributed systems and delivered over networks that can fail, retry, and recover. As a result, Moralis does not guarantee strict ordering or single delivery of events. Instead, it prioritizes reliability and correctness. This page explains:
  • Why events may arrive out of order
  • Why duplicate deliveries are possible
  • How to process events safely using idempotency

​
Why Ordering Is Not Guaranteed

Events may arrive out of order due to:
  • Network latency and retries
  • Automatic retry behavior on delivery failure
  • Manual replay of historical events
  • Confirmed and unconfirmed events being delivered separately
  • Regional delivery differences
This behavior is expected and intentional. Delivery mechanics:

​
What You Can Rely On Instead

Every webhook payload includes stable identifiers that allow you to reason about order and uniqueness:
  • Chain ID
  • Block number
  • Transaction hash
  • Log index (for contract events)
  • Confirmation state (confirmed)
Payload reference: These fields let you:
  • Deduplicate events
  • Sort events deterministically
  • Reconcile final state safely

​
What Idempotency Means

Idempotent processing means:
Handling the same event multiple times produces the same result as handling it once.
This is essential because:
  • Webhooks may be retried automatically
  • Replays intentionally resend historical events
  • Network failures may cause duplicate deliveries
Retry and replay behavior:

​
Use deterministic event keys

Common approaches include:
  • transactionHash
  • transactionHash + logIndex
  • streamId + transactionHash
Store processed keys and ignore duplicates.

​
Treat unconfirmed events as provisional

  • Use confirmed: false for real-time UX
  • Persist state only on confirmed: true
Confirmation model:

​
Design replays to be safe

Replays should:
  • Reapply state deterministically
  • Overwrite or reconcile existing records
  • Never assume data is “new”
Recovery workflows:

​
Common Mistakes to Avoid

  • Assuming webhook arrival order equals block order
  • Using arrival timestamps as a source of truth
  • Mutating permanent state on unconfirmed events
  • Failing or crashing on duplicate payloads

​
Relationship to Delivery Guarantees

TopicPage
Reliable deliveryDelivery Guarantees
Retry behaviorRetries & Replays
Confirmation modelConfirmation & Finality
Re-org handlingRe-org Handling

​
Best Practices Summary

  • Expect duplicates
  • Do not assume ordering
  • Persist only confirmed state
  • Make handlers idempotent by design

​
Next Steps