# 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/list` * Check 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://support.ordereazi.com/developers/webhooks/delivery-and-troubleshooting.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.