Handle webhook suspension
Webhook suspension refers to the disabling of the webhook notifications for shipment events due to an error.
If the receiving endpoint (the system where the notifications are sent) is down or encounters errors, for example, time out, invalid data, SAPIENT may suspend sending further webhook notifications to avoid overwhelming the system.
Quick Recovery
Reactivate suspended webhooks immediately using the Activate toggle in the GUI to minimise data loss.
Monitoring Setup
Set up dedicated webhook monitoring before suspension notifications are triggered for better reliability.
How webhook suspension works
Suspension Process
When your webhook endpoint is down or encounters errors, SAPIENT follows a structured retry process before suspending the webhook:
- Error Detection: The system detects issues like timeouts, invalid data, or server errors
- Retry Attempts: Multiple retry attempts are made following specific intervals
- Threshold Exceeded: If all retry attempts fail, the webhook is suspended
- Notification: An email is sent to the primary user registered for the customer
Primary User: Set up during customer onboarding. Contact Intersoft's onboarding team to change the primary user.
Retry Schedule
The system follows this retry schedule before suspending a webhook:
| Retry ID | Retry Count | Interval |
|---|---|---|
| 1 | 0 | 5 minutes* |
| 2 | 1 | 10 minutes |
| 3 | 2 | 15 minutes |
| 4 | 3 | 30 minutes |
| 5 | 4 | 5 hours |
| 6 | 5 | 18 hours |
| 7 | 6 | 72 hours |
| 8 | 7 | 72 hours |
Reactivation Process
To reactivate a suspended webhook:
- Navigate to the webhook configuration in your GUI
- Toggle the Activate switch to enable the webhook
- Monitor the endpoint to ensure it's functioning properly
ImportantOnce the webhook is suspended, it looses all its tracking data. For example, if a customer reactivates the webhook after one week, they loose one week of the tracking data. Therefore, if you do not want to loose any tracking data, then make sure to activate it promptly.
Error reference
Immediate suspension error codes
The immediate suspension may occur when the retry limit is exceeded. The following table lists the immediate suspension codes that can help you troubleshoot webhook issues:
| Error Code | Description | Details |
|---|---|---|
| 400 | Bad Request | Server cannot understand the request due to client error |
| 402 | Payment Required | Payment required to access the resource (experimental) |
| 403 | Forbidden | No permission to access the resource |
| 410 | Gone | Resource permanently unavailable and intentionally removed |
| 413 | Payload Too Large | Request size exceeds server's file size limit |
| 414 | URL Too Long | Requested URL exceeds server processing limits |
| 415 | Unsupported Media Type | Payload format not supported by server |
| 416 | Range Not Satisfiable | Partial range request does not make sense for resource |
| 417 | Expectation Failed | Server cannot meet 'Expect' header conditions |
| 418 | I'm a teapot | The server refuses the attempt to brew coffee with a teapot |
| 426 | Upgrade Required | The server refuses to perform the request using the current protocol but might be willing to do so after the client upgrades to a different protocol. |
| 428 | Precondition Required | The origin server requires the request to be conditional |
Retry suspension error codes
The system goes in the retry mode due to any temporary failures. In this case, the system retries the deiveries. The following table lists the retry suspension codes that can help you troubleshoot webhook issues:
| Error Code | Description | Details |
|---|---|---|
| 401 | Unauthorized | Request lacks valid authentication credentials |
| 404 | Not Found | The server cannot find the requested resource |
| 405 | Method Not Allowed | The request method is known by the server but is not supported by the target resource. |
| 406 | Not Acceptable | The web server does not find any content that conforms to the criteria given by the user agent. |
| 407 | Proxy Authentication Required | Authentication is needed to be done by a proxy |
| 408 | Request Timeout | Server attempts to shut down any unused connection |
| 409 | Conflict | The request conflicts with the current state of the server |
| 411 | Length Required | Server rejected the request because the Content-Length header field is not defined |
| 412 | Precondition Failed | The request indicates preconditions in its headers which the server does not meet |
| 425 | Too Early | The server is unwilling to risk processing a request that might be replayed |
| 429 | Too Many Requests | The user has sent too many requests in a given amount of time (rate limiting) |
| 431 | Request Header Fields Too Large | The server is unwilling to process the request because its header fields are too large |
| 451 | Unavailable For Legal Reasons | The user agent requested a resource that cannot legally be provided |
Best Practices
Prevention
- Implement robust error handling
- Set up monitoring and alerting
- Ensure endpoint reliability
- Test webhook endpoints regularly
Recovery
- Monitor suspension notifications
- Reactivate webhooks promptly
- Verify endpoint functionality
- Check for missed tracking data
See also
Set Up Tracking Webhook Connection
Automate the instantaneous flow of information regarding the status of shipments.
Add Tracking Account
Establish your tracking account for seamless integration.
Set Up Manifest Webhook
Enable webhook notifications for manifest-level tracking operations.
Track Events and Milestones
Understand tracking events and milestone data.
Updated 17 days ago