Skip to main content

​
Overview

Webhook Delivery explains how Streams sends events to your backend, from the moment an on-chain event occurs to when your server successfully processes it. Moralis Streams is designed for high reliability at scale, handling retries, reorgs, confirmation logic, and backpressure automatically - so you can focus on building application logic. This page covers delivery behavior. For payload structure, configuration, or retries, see the linked pages below.

​
How Webhook Delivery Works

At a high level:
  1. A block is produced on-chain
  2. Streams detects matching events
  3. Moralis sends a webhook to your endpoint
  4. Delivery is retried automatically if it fails
  5. Events are finalized once the block is confirmed
You do not need to poll or manage state manually. To get started with creating streams, see:

​
Confirmed vs Unconfirmed Webhooks

For most blockchain events, Streams delivers two webhooks:

​
1. Unconfirmed (confirmed: false)

  • Sent as soon as the block is mined
  • Low latency
  • Block may still be reorganized

​
2. Confirmed (confirmed: true)

  • Sent after sufficient confirmations
  • Safe to persist as final state
This approach gives you real-time responsiveness without sacrificing correctness.
Edge case: In rare scenarios, a confirmed webhook may arrive before the unconfirmed one. Your system should handle both cases gracefully.
For chain-specific confirmation thresholds, see: For how reorgs are handled internally:

​
Delivery Guarantees

Moralis provides at-least-once delivery for all webhooks. This means:
  • A webhook will be delivered until your server acknowledges it
  • Failed deliveries are retried automatically
  • Duplicate deliveries are possible (and expected)
Your webhook handler must be idempotent. Read more about Delivery Guarantees.

​
Automatic Retries

If your server fails to respond successfully:
  • Streams retries delivery using an exponential backoff schedule
  • Retries continue for up to 24 hours
  • Retry count is included in the payload
Retry behavior is automatic and requires no configuration. Detailed retry schedules and replay options:

​
Queueing & Backpressure

To protect system stability, Streams maintains an internal delivery queue per webhook URL. Key points:
  • If your server processes webhooks too slowly, events queue up
  • The current queue size is sent in the x-queue-size response header
  • If the queue reaches its limit, the stream may enter an error state
To avoid this:
  • Ensure your webhook endpoint responds quickly
  • Offload heavy processing to background workers
  • Deploy streams in a region close to your backend
Read more about Error Handling.

​
Ordering Guarantees

Webhook delivery is not strictly ordered. This can happen due to:
  • Network retries
  • Regional failover
  • Confirmed vs unconfirmed delivery timing
You should not assume ordering and should always rely on:
  • Transaction hash
  • Log index
  • Block number
  • Confirmation state
Explore Webhook Payload structure details.

​
Failure States

Streams have multiple operational states:
StatusDescription
activeStream is live and delivering webhooks
pausedStream is temporarily disabled
errorStream encountered a configuration or delivery error
terminatedStream was automatically stopped after 24 hours in error state
Email notifications are sent when:
  • A stream enters error state
  • A stream is terminated
Read more about Stream Lifecycle details.

​
Security & Verification

Every webhook includes an x-signature header. You must verify this signature to ensure the payload originated from Moralis. Signature verification is covered here Webhook Security.

​
When to Use Replays

If your system was down or missed events:
  • You can replay individual failed webhooks
  • You can replay entire blocks for a stream
Replay tools are covered in Retries & Replays.

​
Common Next Steps

Depending on what you’re building: