Retry Policy

This document provides a comprehensive explanation of how the POS Hub platform manages the delivery of webhooks to external endpoints, with a particular focus on retry behavior. By understanding these guidelines, you can ensure that your application receives webhook events reliably and can handle them appropriately, even in the face of transient errors or unexpected downtime.

Introduction

Whenever a webhook event is triggered within the POS Hub platform—whether it’s a notification about a newly created order, an update to a delivery’s status, or a change in the product catalog—the system attempts to send a JSON payload to a preconfigured external URL. If that URL is unreachable, responds slowly, or returns an error, the platform will make repeated attempts to deliver the same webhook event over a defined period.

This document describes the timing of each retry, which HTTP status codes cause the system to retry, the duration of each attempt before timing out, and the overall timeframe during which POS Hub will continue trying to deliver a particular event.

Delivery and Retry Timeline

When a webhook event is ready to be dispatched, POS Hub sends an HTTP request to your specified endpoint. If your endpoint successfully responds with a 2xx HTTP status code, the event is considered delivered. However, if a failure occurs—because of a timeout, unreachable endpoint, or specific server errors—the platform triggers the retry mechanism.

Retry Interval

The system waits 30 seconds before making a second attempt to deliver a failed event. This 30-second gap applies to every subsequent delivery attempt as well. The goal is to give your endpoint a brief window to recover from transient issues before trying again.

Maximum Retry Duration

POS Hub continues to issue retry attempts for up to 10 minutes following the event’s initial failed delivery attempt. If the webhook is not acknowledged (with a 2xx code) within that 10-minute window, the system stops trying altogether. At that point, the event is flagged as undeliverable unless you have an external mechanism in place for manual replay or inspection of failed webhooks.

Timeout Behavior

Each outbound request from POS Hub to your endpoint waits up to 29 seconds for a response. If no response is received within that timeframe, the attempt is considered a timeout. The event is then queued for another delivery attempt, subject to the same 30-second retry interval and the 10-minute maximum duration.

This 29-second limit exists to prevent stalled connections from lingering indefinitely and to provide clarity on when the system considers a delivery attempt to have definitively failed.

Retryable Status Codes

Certain types of failures are seen as potentially transient or resolvable with subsequent attempts. In particular, if your endpoint returns any of the following HTTP status codes, POS Hub interprets the failure as temporary and initiates a retry:

• 429 – Too Many Requests
• 500 – Internal Server Error
• 502 – Bad Gateway
• 503 – Service Unavailable
• 504 – Gateway Timeout

By contrast, certain other status codes (like 400, 404, 401, etc.) typically indicate that a retried request is unlikely to succeed. These are treated as permanent failures, and the system discontinues retries after encountering such a response.

Webhook Event Examples

Although this document focuses on the mechanics of retries, it can be helpful to understand the types of events that benefit from this resilience:

1. Order Notifications – Webhooks that inform an external ordering or reporting system about the creation, update, or cancellation of orders.
2. Delivery Status Updates – Events that share up-to-date information about the progress of a delivery—helpful for last-mile delivery tracking.
3. Catalog and Menu Changes – Webhooks that notify partner systems when new products, modifiers, or prices are published or updated.

INFO

Each webhook event adheres to a JSON schema defined in the POS Hub API documentation. When designing your webhook handler, ensure that it can parse these payloads effectively and respond with a 2xx code promptly.

Practical Considerations

To make the most of the retry policy and avoid accumulating failed events in your logs:

1. Respond Quickly: As soon as you successfully receive and enqueue the webhook data, respond with a 2xx code. If you need to do longer processing, consider doing it asynchronously in your application after sending the successful response.
2. Implement Idempotency: Because retries may cause a webhook to be delivered multiple times, design your system so that processing the same payload repeatedly won’t cause data duplication or other inconsistencies. This can involve checking for unique identifiers within the payload and storing the record of previously processed events.
3. Monitor Your Endpoint: Keep track of response times and error rates. If you see a spike in timeouts or 5xx errors, investigate potential service instability, network issues, or load problems.

As an application owner, we provide you with basic analytics and logs to help you monitor the delivery of webhook events. you can find this information within the POS Hub Developers area.

Summary

POS Hub’s webhook retry policy ensures robust delivery of important event notifications by:

• Sending each initial request and, if needed, repeating attempts in 30-second intervals.
• Limiting the overall retry period to a 10-minute window.
• Timing out each request after 29 seconds of inactivity.
• Automatically retrying for 429, 500, 502, 503, and 504 status codes.

By adhering to this policy and building your endpoint to handle possible duplicate deliveries, you can take full advantage of POS Hub’s reliable event notification system. Properly handling webhook retries reduces the risk of missing critical data while providing clear visibility into any delivery failures that may arise.

Reference Table

Parameter	Value	Notes
Initial Wait Between Retries	30 seconds	Every retry is spaced by 30 seconds.
Maximum Retry Window	10 minutes	After 10 minutes of failures, no further retry attempts occur.
Request Timeout	29 seconds	If your endpoint doesn’t respond within 29 seconds, the request is considered a failure.
Retryable Error Codes	429, 500, 502, 503, 504	These indicate transient issues that could be resolved in subsequent attempts.
Non-Retryable Errors	All other 4xx/5xx codes (e.g., 400, 404)	Treated as final failures; POS Hub does not retry them.

Use this table as a quick reference guide when configuring or troubleshooting your webhook endpoints.

below is a diagram that illustrates the retry flow for webhook events: