Delivery and Reliability

Real-Time Event Streams are designed for at-least-once delivery with automatic retry of transient failures. This page describes the delivery, retry policy, failed events log, and headers you can use to deduplicate on your side.

​

Latency

Events will be delivered to webhook endpoints within p95 ≤ 120 seconds of ingestion under normal load. This is the baseline definition of “real-time” for the feature.

​

Batching

Events are batched per Sync before delivery. Mixpanel flushes a batch when it
reaches 500 events or 5 seconds since the first event in the batch,
whichever comes first.

Each flush is a single `POST` whose body is a **JSON array** of rendered events,
even when the array contains only one event: ​json
[
{ “event”: “Signup”, “user_id”: “abc” },
{ “event”: “Signup”, “user_id”: “def” }
]

Your endpoint must accept a JSON array and return a single 2xx for the whole
batch. A non-2xx fails the entire batch (all events are retried together).

​

Retry policy

Transient delivery failures are retried automatically. Permanent failures are not retried and surface as configuration errors.

​

What gets retried

​

Backoff schedule

Up to 4 retries (1 initial + 4 retries) with exponential backoff starting at 200ms, totaling roughly 3 seconds: For 429 responses, the Retry-After header is honored when present, capped at 10 seconds.

​

4xx errors

401 and 403 responses indicate an authentication failure. These are terminal:

• The Sync is paused immediately.
• The Destination surfaces an authentication error.
• A project admin must fix credentials or the webhook URL before restarting.

Other 4xx responses (e.g., 400, 404, 422) indicate the destination is unreachable or misconfigured and are retried like transient failures. If retries exhaust:

• The Sync is paused.
• The error state is visible in the UI so a project admin can fix the endpoint or payload template.

​

Failed Events Log

When events cannot be delivered after retries, they move to a failed events log retained in-product for debugging. Each entry is an aggregated roll-up per failed stream. One row per Sync + status code + error type + count of failed events in that window

​

Alerting on failure

Failure alerting happens when a terminal failure is encountered (auth error, or non-auth 4xx after retries): the Sync moves into the error state and pauses streaming until a Project Admin re-enables it. See States and monitoring for state transitions.

​

Rate limits and backpressure

When a destination returns 429 Too Many Requests:

• The request is retried after respecting the Retry-After header (if present, capped at 10 seconds).
• If retries exhaust, the Sync enters the error state and pauses.

See States and monitoring for the full list of Sync states.

​

What to build on your side

To get the most out of the delivery model:

• Return 2xx quickly. Acknowledge the request before doing heavy downstream work; process asynchronously on your side.
• Return 4xx for permanent errors, 5xx for transient ones. This lets Mixpanel retry the right failures and surface the right errors.
• Honor Retry-After on 429 responses so Mixpanel can back off cleanly.

​

Next steps