Delivery and Troubleshooting
🚚 Webhook Delivery and Troubleshooting
Understanding how OrderEazi delivers webhooks helps you build reliable integrations. This page covers timing, retries, failure handling, and best practices for your receiving endpoint.
⚙️ Delivery Mechanics
Webhooks are not sent instantly when an event occurs. Instead, they follow a queue-based delivery model.
How delivery works:
When an event fires, a queue entry is created immediately
A background processor runs every minute and dispatches all pending entries
Each entry is sent as an HTTP POST to the registered URL
When multiple entries are queued, there is a 5-second delay between each dispatch
This means you can expect to receive a webhook within 1-2 minutes of the event occurring.
🔄 Retry Logic
If your endpoint returns a non-2xx HTTP status code, OrderEazi treats the delivery as failed.
Failed deliveries are retried on subsequent processor runs (approximately every minute)
After 3 failed attempts, the webhook is permanently marked as failed (dead-lettered)
Dead-lettered webhooks are excluded from future automatic processing
The first 255 characters of your error response body are stored alongside the queue entry. Return meaningful error messages to aid debugging.
🗑️ Queue Retention
Webhook queue entries are automatically deleted after 30 days, regardless of whether they were successfully delivered or permanently failed.
If you need to retain webhook data longer than 30 days, store the payloads on your side when you receive them.
🔁 Resending Failed Webhooks
Failed webhooks can be resent from the OrderEazi UI at Integrations > Webhooks.
When a webhook is resent:
The original queue entry is marked as permanently failed
A fresh queue entry is created with the same payload
The new entry is dispatched immediately (not queued for the next processor run)
💡 Best Practices for Receivers
Build your webhook endpoint with these guidelines:
Respond quickly - return a 2xx status within a few seconds. If you need to do heavy processing, store the payload and process it asynchronously.
Use X-OE-Webhook-Id for idempotency - OrderEazi includes a unique ID with every dispatch. Store this ID and check for duplicates before processing, in case a webhook is delivered more than once.
Use HTTPS - always register HTTPS endpoints. HTTP endpoints will work but are not recommended for production use.
Return meaningful errors - if you cannot process a webhook, return a descriptive error message in the response body. The first 255 characters are stored in OrderEazi for debugging.
Handle retries gracefully - your endpoint may receive the same event multiple times if earlier attempts failed. Design your processing to be idempotent.
🕐 Webhook Registry Caching
Webhook registrations are cached for 1 minute. After you create or delete a webhook via the API, it may take up to 1 minute for the change to take effect.
🔍 Debugging Webhook Issues
If your endpoint is not receiving webhooks:
Verify the webhook is registered by calling
GET /api/webhook/listCheck the webhook queue in Integrations > Webhooks in the OrderEazi UI
Queue entries show: delivery status, retry count, and error message or success response
Look for dead-lettered entries (these have exhausted all retries)
Confirm your endpoint is publicly accessible and returns a 2xx status
If a specific webhook failed:
Check the error field on the queue entry for the HTTP status code and response body
Resend the webhook from the UI to retry delivery immediately
Verify your endpoint can handle the payload size (some payloads, like products with many variants, can be large)
✅ Summary
Webhooks are delivered via a queue processor that runs every minute
Failed deliveries are retried up to 3 times before being dead-lettered
Queue entries are retained for 30 days
Failed webhooks can be resent manually from the OrderEazi UI
Design your endpoint to respond quickly, handle duplicates, and return meaningful errors
Use the X-OE-Webhook-Id header for idempotency
Last updated