- Webhooks
- Webhook Retry Mechanism
Webhooks
Webhook Retry Mechanism
When our system sends a webhook callback to a merchant's endpoint and fails to receive a valid response, the system will automatically attempt to resend (retry) it. The goal is to ensure reliable communication between our system and the merchant, even during temporary disruptions like timeouts, service downtime, or other errors. Each retry is performed with a 1-minute interval between attempts. If the final attempt still fails, we will stop retrying and send a webhook failure notification to the merchant's email.
⚙️ Retry Mechanism
| Condition / HTTP Status | Handling Function | $retryCount Value | Maximum Retries | Description |
|---|---|---|---|---|
| 500 (Internal Server Error) | handleFailedHttpResponse() | 1 | 1 retry attempt | The merchant’s server is experiencing a problem. |
| 503 (Service Unavailable) | handleFailedHttpResponse() | 4 | 4 retry attempts | The merchant is temporarily inaccessible. |
| 400 / 404 (Bad Request / Not Found) | handleFailedHttpResponse() | 2 | 2 retry attempts | The endpoint might be incorrect or temporarily unavailable. |
| Redirect 307 / 308 | retryRedirect() | - | 5 retry attempts (redirect) | Redirects are followed up to 5 times. |
| Redirect 301 / 302 / 303 | handleFailedHttpResponse() | - | 0 (no retry) | Redirect is not followed (the endpoint needs to be updated). |
| Exception (including cURL error) | catch(Exception $e) | 1 | 1 retry attempt | For example, a timeout, DNS error, or connection failure. |
| Other (default case) | handleFailedHttpResponse() | 5 | 5 retry attempts | For other statuses not covered by the conditions above. |
⏱️ Interval Between Retries
- Each retry is performed 1 minute after the previous attempt.
- Retries are stopped once the maximum limit specified in the table above is reached.
🧾 Example Retry Flow (HTTP 503)
| Attempt | Response Status | System Action | Delay Before Next Try |
|---|---|---|---|
| #1 | 503 | 1st Retry | 1 minute |
| #2 | 503 | 2nd Retry | 1 minute |
| #3 | 503 | 3rd Retry | 1 minute |
| #4 | 503 | 4th Retry | Done (no more retries) |
Total maximum retry time (if all attempts fail): approximately 4 minutes.
📩 Failure Notification
If the webhook still fails after the final retry attempt, our system will:
- Log the failure in the database (accessible via the callback menu on the merchant dashboard).
- Send a failure notification to the merchant’s email.
Merchants are advised to:
- Ensure the webhook endpoint returns an HTTP status of 200–299.
- Maintain server availability to receive callbacks from us.
- Avoid using redirects (301–308) on the webhook URL.
💡 Technical Notes
- Retry counts are stored using a cache with a 15-minute TTL.
- All callbacks and retries are logged in our database for auditing and debugging purposes.