Retry strategy
Hubpay automatically retries webhook deliveries that fail, using an exponential backoff schedule. This ensures your system has multiple opportunities to receive each event, even during temporary outages.
What counts as a successful delivery
A webhook delivery is considered successful when your endpoint returns an HTTP 2xx status code (200–299) within 15 seconds of receiving the request.
Any other response — including 3xx redirects, 4xx client errors, 5xx server errors, or a timeout — is treated as a failure and will trigger a retry.
Retry schedule
When a delivery fails, Hubpay retries using the following exponential backoff schedule:
| Attempt | Delay after previous attempt | Approximate cumulative time |
|---|---|---|
| 1 | Immediately | 0 seconds |
| 2 | 5 seconds | 5 seconds |
| 3 | 5 minutes | ~5 minutes |
| 4 | 30 minutes | ~35 minutes |
| 5 | 2 hours | ~2 hours 35 minutes |
| 6 | 5 hours | ~7 hours 35 minutes |
| 7 | 10 hours | ~17 hours 35 minutes |
| 8 | 10 hours | ~27 hours 35 minutes |
If an endpoint is removed or disabled, delivery attempts to the endpoint will be disabled as well.
For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.
After all retries are exhausted
If all delivery attempts fail, as outlined in the schedule above, the message is marked as Failed. Failed messages are not retried automatically beyond this schedule.
Endpoint disabling
If all delivery attempts to a specific endpoint consistently fail over a period of 5 days, the endpoint may be automatically disabled to prevent continued failed deliveries.
Best practices
- Respond quickly — return a
2xxresponse as soon as the payload is accepted, before doing any heavy processing. Process the event asynchronously if needed. - Be idempotent — because retries can deliver the same event more than once, your handler should produce the same result regardless of how many times it receives a given event. Use the event
idfield to detect duplicates. - Monitor your endpoint — if your endpoint is consistently failing, investigate and resolve the issue promptly to avoid endpoint disabling and missed events.
- Use HTTPS — always use HTTPS endpoints to ensure webhook payloads are encrypted in transit.