Skip to main content

​
Overview

Streams is designed for reliable, at-least-once delivery of webhook events.
While Moralis handles retries and failure recovery automatically, errors can still occur—most commonly due to webhook endpoint availability or throughput constraints. This page explains:
  • How delivery failures are handled
  • When streams enter error or terminated states
  • How retries, replays, and recovery work
  • What actions you should take in production

​
Delivery Guarantees (Important Context)

Moralis guarantees at-least-once delivery of webhooks while a stream is active. This means:
  • Webhooks may be retried
  • Duplicate deliveries are possible
  • Your webhook handler must be idempotent
Correctness is prioritised over strict ordering.

​
Automatic Webhook Retries

If a webhook delivery fails (timeout, network error, non-2xx response), Moralis automatically retries delivery using an exponential backoff strategy.

​
Retry schedule

Retries apply only to delivery failures.
They do not reprocess blocks or regenerate events.

​
Error State

A stream may enter the error state under the following conditions:

​
1. Low webhook success rate

If the webhook success rate for a stream drops below 70%, the stream enters the error state.

​
2. Delivery backlog (queue saturation)

If your server cannot consume webhooks fast enough:
  • A delivery queue builds up
  • The queue reaches its maximum size (10,000 events)
  • The stream is placed into the error state
You can monitor queue pressure using the x-queue-size response header.

​
Behaviour in Error State

When a stream is in the error state:
  • Webhook delivery is paused
  • Events are not delivered
  • Blocks are still evaluated
  • Retry scheduling resumes once the stream is reactivated
An email notification is sent when a stream enters this state.

​
Terminated State

If a stream remains in the error state for 24 hours, it is automatically terminated.

​
Behaviour in Terminated State

A terminated stream:
  • Does not send webhooks
  • Does not process new blocks
  • Drops all subsequent events permanently
  • Cannot be resumed
An email notification is sent when termination occurs. To recover, a new stream must be created.

​
Webhook Success Rate

Each stream tracks a webhook success rate per webhook URL:
  • Starts at 100%
  • Each failed delivery reduces the rate by 1%
  • Each successful delivery increases the rate by 1%
  • Capped between 0% and 100%
If the success rate falls below 70%, the stream enters the error state.

​
Viewing Failed Webhooks

Failed webhook deliveries are retained for a limited time (plan-dependent, up to 7 days).

​
Retrieve failed deliveries

Each failed delivery includes:
  • Webhook payload
  • Error message
  • Stream ID
  • Timestamp
  • Unique history ID

​
Replaying Failed Webhooks

Failed webhooks can be replayed manually.

​
Replay a failed webhook

Replayed webhooks are delivered with the same payload as the original attempt.
Replays do not regenerate events or reprocess blocks.
For block-level recovery, use Replay Block (see Retries & Replays).

​
Best Practices to Avoid Errors

  • Ensure webhook endpoints respond quickly and consistently
  • Treat webhook handling as idempotent
  • Monitor x-queue-size headers
  • Choose a stream region close to your backend
  • Pause streams during planned outages
  • Act promptly on error-state email notifications

​
Summary

  • Delivery failures trigger automatic retries
  • Prolonged failures cause streams to enter error
  • Error state pauses delivery but preserves configuration
  • 24 hours in error results in termination
  • Failed deliveries can be replayed
  • Block-level recovery requires replay