Skip to main content
This page describes how Omni Z-API delivers events to your endpoint and what happens when a delivery fails. It applies to every webhook type — channel, template and default — in both the default and the Z-API formats.

​
Respond with 2xx within 5 seconds

A delivery succeeds when your endpoint responds with a 2xx status within 5 seconds. Receive the event, store it and respond. Do the heavy processing later, outside the request. A slow response counts as a failure, and the event is sent again.

​
When the event is sent again

Each wait counts from the previous attempt: That is up to 7 attempts, within 23 hours of the event. After that, the event is no longer sent.
If your endpoint keeps failing, Omni Z-API pauses deliveries to your address for a while and then resumes them. Events from that pause are not lost: they follow the same attempts, within the 23-hour window.

​
Headers on each delivery

​
Deduplicate by x-webhook-delivery-id

The same delivery can arrive more than once. This happens, for example, when your endpoint processed the event but took more than 5 seconds to respond. Keep the x-webhook-delivery-id values you already processed for at least 24 hours, and discard repeats.

​
Arrival order is not guaranteed

Events are sent in the order they happen. But an event that failed is sent again minutes or hours later, while the following events keep being delivered. So a message’s “read” status can arrive before the “delivered” status that failed on its first attempt.
  • Order by the event time in the body (in the default format, the moment field), not by arrival time.
  • For statuses, only move forward: ignore a status older than the one you already stored.

​
When your endpoint is down

Events are not lost: they follow the attempts above for up to 23 hours. When your endpoint comes back, the delayed events arrive together with the new ones. Prepare your endpoint for a higher volume for a few minutes.