Webhooks in SuiteFleet allow you to receive real-time notifications when specific events occur in your account.
🔧 Overview
A webhook is an HTTP endpoint (URL) that SuiteFleet calls whenever a selected trigger is activated.
Each call is a POST request containing the event data in JSON format.
They can be registered at the merchant level, enabling your system to automatically react to operational changes — such as delivery updates, status transitions, or task assignments.
You can configure:
- Which events (triggers) you want to listen for
- Whether to receive payloads as arrays or as single JSON objects
- Optional authorization using a Client ID and Secret
- The webhook activation status (Active / Inactive)
💡 You can test your webhook endpoint easily using free tools such as https://webhook.site/.
📩 Request Format
Array Format (Default)
By default, webhook notifications are sent as a JSON array — allowing batch processing of multiple events at once.
Example:
[
{
"id": 9396,
"awb": "762-93036975",
"customerOrderNumber": null,
"deliveryDate": "2025-10-01",
"deliveryStartTime": "06:00:00",
"deliveryEndTime": "10:00:00",
"type": "DELIVERY",
"deliveryType": "STANDARD",
"status": "OUT_FOR_DELIVERY",
"driver": null,
"consignee": {
"id": 3460,
"name": "Ibrahim",
"location": {
"addressLine1": "Riyadh, Hamra, Saudi Arabia",
"addressLine2": null,
"addressLine3": null,
"addressCode": null,
"district": "Hamra District",
"countryId": 187,
"city": "Riyadh",
"contactPhone": "+9665XXXXXXX",
"contactEmail": null,
"countryCode": "SA",
"latitude": 24.77809086,
"longitude": 46.74077869,
"stateProvince": null,
"zip": null,
"contactFax": null,
"state": null
}
},
"deliveryInformation": {
"id": 9396,
"deliveryDate": null,
"deliveryStartTime": null,
"deliveryEndTime": null,
"deliveryBoxes": null,
"collectedAmount": null,
"failureReasonComment": null,
"reason": null,
"numberOfAttempts": null,
"completionLatitude": null,
"completionLongitude": null,
"driverComment": null,
"consigneeRating": null,
"consigneeComment": null,
"recipientName": null,
"signature": null,
"bagsReturned": null,
"icePacksReturned": null,
"posTransactionId": null,
"photos": null,
"taskFailureReason": null,
"taskAssetsReturned": null,
"codPaymentMethod": null
},
"hangers": null,
"shipFrom": {
"id": 3087,
"name": "Merchant Warehouse",
"address": null,
"latitude": null,
"longitude": null,
"addressLine1": "Centre Tower",
"addressLine2": null,
"addressLine3": null,
"addressCode": null,
"district": "Riyadh",
"city": "Riyadh",
"stateProvince": null,
"zip": null,
"contactPhone": "+9661XXXXXXX",
"contactFax": null,
"contactEmail": null,
"geofence": null,
"countryId": 187,
"countryCode": "SA",
"state": null
},
"customer": {
"id": 37,
"name": "Travel Light",
"code": "762",
"phoneNumber": "+9661XXXXXXX",
"email": null,
"partialDelivery": false,
"taskAssetTrackingEnabled": false,
"defaultTaskAssetType": null
},
"shipmentPackages": [
{
"id": 13163,
"packageStatus": "OUT_FOR_DELIVERY",
"trackingId": "762-93036975-1"
},
{
"id": 13164,
"packageStatus": "OUT_FOR_DELIVERY",
"trackingId": "762-93036975-2"
}
],
"amazonInformation": null,
"totalShipmentValueAmount": null,
"totalDeclaredGrossWeight": null,
"totalShipmentQuantity": 15,
"codAmount": null,
"totalShipmentValueCurrency": null,
"signatureRequired": false,
"ageVerificationRequired": false,
"codCurrency": null,
"createdDate": "2025-10-01T13:43:48",
"volume": 0,
"details": null,
"notes": null,
"timestamp": 1760206755813,
"action": "TASK_STATUS_UPDATED_TO_OUT_FOR_DELIVERY",
"smsNotifications": false,
"referenceNumber": null,
"trackingUrl": "https://go.suitefleet.com/XXXXX",
"locateConsigneeUrl": null,
"highValueTask": false,
"otp": null,
"pickedUpTime": null,
"shipmentCategory": null,
"remoteArea": false
}
]
Object Format
If your system expects a single JSON object instead of an array, append the query parameter
?sf-format=object to your endpoint URL.
{
"id": 9394,
"awb": "762-45003040",
"customerOrderNumber": null,
"deliveryDate": "2025-10-01",
"deliveryStartTime": "06:00:00",
"deliveryEndTime": "10:00:00",
"type": "DELIVERY",
"deliveryType": "STANDARD",
"status": "OUT_FOR_DELIVERY",
"driver": null,
"consignee": {
"id": 3458,
"name": "Abdullah S.",
"location": {
"addressLine1": "Riyadh, Zahrat Laban, Saudi Arabia",
"addressLine2": null,
"addressLine3": null,
"addressCode": null,
"district": "Zahrat Laban District",
"countryId": 187,
"city": "Riyadh",
"contactPhone": "+9665XXXXXXX",
"contactEmail": null,
"countryCode": "SA",
"latitude": 24.63574129,
"longitude": 46.56654769,
"stateProvince": null,
"zip": null,
"contactFax": null,
"state": null
}
},
"deliveryInformation": {
"id": 9394,
"deliveryDate": null,
"deliveryStartTime": null,
"deliveryEndTime": null,
"deliveryBoxes": null,
"collectedAmount": null,
"failureReasonComment": null,
"reason": null,
"numberOfAttempts": null,
"completionLatitude": null,
"completionLongitude": null,
"driverComment": null,
"consigneeRating": null,
"consigneeComment": null,
"recipientName": null,
"signature": null,
"bagsReturned": null,
"icePacksReturned": null,
"posTransactionId": null,
"photos": null,
"taskFailureReason": null,
"taskAssetsReturned": null,
"codPaymentMethod": null
},
"shipFrom": {
"id": 3087,
"name": "Merchant Warehouse",
"address": null,
"latitude": null,
"longitude": null,
"addressLine1": "Centre Tower",
"district": "Riyadh",
"city": "Riyadh",
"contactPhone": "+9661XXXXXXX",
"countryCode": "SA"
},
"customer": {
"id": 37,
"name": "Travel Light",
"code": "762",
"phoneNumber": "+9661XXXXXXX",
"email": null,
"partialDelivery": false,
"taskAssetTrackingEnabled": false
},
"shipmentPackages": [
{
"id": 13143,
"packageStatus": "OUT_FOR_DELIVERY",
"trackingId": "762-45003040-1"
},
{
"id": 13144,
"packageStatus": "OUT_FOR_DELIVERY",
"trackingId": "762-45003040-2"
}
],
"totalShipmentQuantity": 10,
"createdDate": "2025-10-01T13:43:47",
"timestamp": 1760206873493,
"action": "TASK_STATUS_UPDATED_TO_OUT_FOR_DELIVERY",
"trackingUrl": "https://go.suitefleet.com/YYYYY",
"remoteArea": false
}
🚀 Available Triggers
| Event Code | Description |
|---|---|
| TASK_HAS_BEEN_ORDERED | Task has been created. |
| TASK_HAS_BEEN_ASSIGNED | Task has been assigned to a driver. |
| TASK_HAS_BEEN_UPDATED | Task details have been updated. |
| TASK_STATUS_UPDATED_TO_ARRIVED_ON_DC | Task arrived at distribution center. |
| TASK_STATUS_UPDATED_TO_OUT_FOR_DELIVERY | Task out for delivery. |
| TASK_STATUS_UPDATED_TO_PICKED_UP | Task picked up. |
| TASK_STATUS_UPDATED_TO_IN_TRANSIT | Task in transit. |
| TASK_STATUS_UPDATED_TO_DELIVERED | Task successfully delivered. |
| TASK_STATUS_UPDATED_TO_FAILED | Task failed. |
| TASK_STATUS_UPDATED_TO_CANCELED | Task canceled. |
| TASK_STATUS_UPDATED_TO_RESCHEDULED | Task rescheduled. |
| TASK_STATUS_UPDATED_TO_REATTEMPT | Task marked for reattempt. |
| TASK_STATUS_UPDATED_TO_PROCESS_FOR_RETURN | Task processing for return. |
| TASK_STATUS_UPDATED_TO_RETURNED_TO_SHIPPER | Task returned to shipper. |
| TASK_STATUS_UPDATED_TO_HUB_TRANSFER | Task transferred between hubs. |
🔐 Authorization
You can secure your webhook endpoint by registering a Client ID and Client Secret when creating the webhook.
SuiteFleet will include these credentials in the request headers:
X-Client-Id: {your_client_id}
X-Client-Secret: {your_client_secret}
🔄 Webhook Management
| Action | Description |
|---|---|
| Activate / Deactivate | Temporarily enable or disable a webhook without deleting it. |
| Delete | Permanently remove a webhook registration. |
| Update | Modify the URL, triggers, or authorization credentials. |
✅ Response Expectations
- When SuiteFleet sends a POST request to your webhook endpoint, your system should:
- Return HTTP 200 OK to acknowledge successful receipt.
- If your endpoint returns a non-2xx status code, SuiteFleet may retry delivery.
🧠 Best Practices
- Use a unique URL for each environment (Production, UAT, Staging).
- Implement idempotency checks to avoid duplicate event processing.
- Log incoming requests for traceability.
- Secure your endpoint with HTTPS and authentication.
- Test your integration easily with Webhook.site.