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 | 24 hours |
| 8 | 7 | 24 hours |
*Initial retry after first failure
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
Common Error Codes
Understanding these error codes can help you troubleshoot webhook issues:
| Error Code | Description | Details |
|---|---|---|
| 400 | Bad Request | Server cannot understand the request due to client error |
| 401 | Unauthorized | Request lacks valid authentication credentials |
| 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 doesn't make sense for resource |
| 417 | Expectation Failed | Server cannot meet 'Expect' header conditions |
| 418 | I'm a teapot | Easter egg status code (not used in practice) |
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 18 days ago