WEBHOOK for ORDER
There are 3 types of webhook for now, newOrders, orderStatus and shipmentError.
OTO will push updates to the registered webhook endpoint for the orderStatus type whenever an order status changes. This includes statuses such as Processing, Delivered, Returned, and more.
OTO will push an update via the shipmentError webhook type, providing details about the error, if an error occurs while an order shipment.
OTO will push the order details to you through the newOrders webhook type, If you need to create an existing order in a different WMS system.
timestamp value belongs to UTC time zone.
{
"orderId": "1234",
"status": "shipmentProcessing|delivered|returned|...",
"dcStatus": "status coming from the delivery company",
"note": "optional note to show in order history",
"pickupLocationCode":"code-101",
"driverName": "FirstName LastName",
"driverPhone": "966555444333",
"driverEmail": "driver@example.com",
"driverId":"123124",
"printAWBURL": "https://app.tryoto.com/OTOAWB?enc=eyJpZHMiOlsxMjU1MDkzOF0sImNvbXBhbnlJZCI6MTQ5MjF9",
"trackingNumber": "ASD00123",
"dcTrackingNumber":"983643812",
"trackingUrl": "www.example…...",
"deliveryCompany": "fastExpress",
"timestamp": "1595941360328",
"signature": "S7aLSdZjfZAIf9IOArNgTLI5PXhKDkTeYmrhIfhpE79REU2NLg6Kbeb9KavwRfhV3UhAoFNefnezBEbnn5VO7GlTN4FSESUjf1wKctrfO5gJLFuK2JhIG/p32HSj7A4XvvVYg1xWNOmuM9Ua61zyR7TG5gC0fDipDYcxYAd4vP/RvqWm056IwIRAuevlxLr/EL6JuS9gmNGrAXz733rkjt6RV+ZmFS4VAtSK/WDQOQU3o2CyJipCA6cCo9DRwvHrzUYZNWMakpi70wjhajZRZ5L/4Z7u3D21FsB/LUeRQ9D5niVCaNjDU3e9PQe9ig1frR3LsYOiz5Y0UAyq9izfKg=="
}Signed “orderId:status:timestamp” with “HmacSHA256” method and Base64 Encoded string.
Public key for the signature will be shared on private.
if registered to shipmentError, endpoint will get a payload:
{
"orderId": "7523",
"signature": "bQnNzL2VVwu0joYPfx6Qs3lsoEdVCMR+5xSPdMbABFE=",
"errorMessage": "delivery company not allow to create shipment",
"deliveryCompanyResponse": "error: Shipper.PartyAddress - City/Zipcode is empty",
"errorCode": "deliveryCompanyError",
"deliveryCompany": "aramex",
"timestamp": "1653642441399"
}Signed “orderId:errorCode:timestamp” with “HmacSHA256” method and Base64 Encoded string.
Public key for the signature will be shared on private.
if registered to newOrders, endpoint will get a payload:
{
"order": {
"address": {
"country": "AE",
"address": "46C3+Q7 Dubai - United Arab Emirates",
"city": "Dubai",
"name": "fatmanur",
"mobile": "966513321131",
"state": "Dubai"
},
"warehouseId": 11083,
"grandTotal": 1,
"otoId": 14796940,
"paymentMethod": "paid",
"weight": 1,
"currency": "SAR",
"incrementId": "OID-23331-1035",
"salesChannel": "manual",
"brand": "Example Brand",
"codFee": 0.0,
"items": [
{
"itemId": 12402868,
"qtyOrdered": 1,
"sku": "10143",
"qtyReturned": null,
"productId": "string",
"productName": "string"
"itemType": "string",
}
],
"status": "assignedToWarehouse"
},
"timestamp": 1742822768001
}webhook
Endpoint URL
POST https://api.tryoto.com/rest/v2/webhookExample Request Body
Here is an example of a request body:
{
"method": "post",
"url": "https://webhook.site/3e53c98a-a089-4ca4-9bc4-df10e5a71e4b",
"orderPrefix": "fulfillment",
"timestampFormat": "2025-01-01 13:14:34",
"secretKey": "key1234",
"authorizationKey": "authorizationkey123",
"webhookType": "shipmentError"
}Request Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| method | yes | string | POST or PUT |
| url | yes | string | Your endpoint listens to get OTO webhook payload, when order status changes. exp.https://webhook.site/3e53c98a-a089-4ca4-9bc4-df10e5a71e4b |
| secretKey | no | string | With this key message is signed and receiver validate. |
| authorizationKey | no | string | Secure token used to authenticate and validate incoming webhook requests. |
| timestampFormat | no | string | Exp "yyyy-MM-dd HH:mm:ss" format receiver want to get. |
| orderPrefix | no | string | If orders has prefix in OTO, then put prefix string to be removed before webhook body prepared. |
| webhookType | no | string | shipmentError, sends create shipment error messages; orderStatus sends order status changes. default is orderStatus and newOrders webhook is used to create orders in a different WMS. |
Available Packages: Starter Package, Scale Package, Enterprise Package, Marketplaces
This endpoint enables OTO to send update payloads to the specified URL using the defined method. Optional security measures, such as token authentication and payload validation, can be configured for enhanced security.
Request Parameters:
webhook
Endpoint URL
GET https://api.tryoto.com/rest/v2/webhookRequest Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| id | no | string | id of the webhook |
Available Packages: Starter Package, Scale Package, Enterprise Package, Marketplaces
This endpoint allows you to retrieve a list of all registered webhook definitions. It provides detailed information about each webhook, including its configuration and associated event triggers, enabling you to manage and review your webhook integrations effectively.
Note: You can filter by id if you know the id of the webhook.
Request Parameters:
webhook
Endpoint URL
PUT https://api.tryoto.com/rest/v2/webhookExample Request Body
Here is an example of a request body:
{
"id": 59,
"method": "post",
"url": "https://webhook.site/3e53c98a-a089-4ca4-9bc4-df10e5a71e4b",
"orderPrefix": "test-2",
"timestampFormat": "2025-01-01 10:10:10",
"secretKey": "secret123",
"authorizationKey": "authorizationkey123",
"webhookType": "orderStatus"
}Request Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Id of the webhook record. |
| method | yes | string | POST or PUT |
| url | yes | string | Your endpoint listens to get OTO webhook payload, when order status changes. exp.https://webhook.site/3e53c98a-a089-4ca4-9bc4-df10e5a71e4b |
| secretKey | no | string | With this key message is signed and receiver validate. |
| authorizationKey | no | string | Authorization key. |
| timestampFormat | no | string | Exp "yyyy-MM-dd HH:mm:ss" format receiver want to get. |
| orderPrefix | no | string | If orders has prefix in OTO, then put prefix string to be removed before webhook body prepared. |
| webhookType | no | string | shipmentError, sends create shipment error messages; orderStatus sends order status changes. default is orderStatus and newOrders webhook is used to create orders in a different WMS. |
Available Packages: Starter Package, Scale Package, Enterprise Package, Marketplaces
This API endpoint allows updating an already registered webhook by providing its unique ID. This ensures you can modify existing webhook configurations, such as URL, secretKey, or other parameters, without needing to delete and recreate it.
Request Parameters:
webhook
Endpoint URL
DELETE https://api.tryoto.com/rest/v2/webhookRequest Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| id | yes | string | Id of the webhook record. |
Available Packages: Starter Package, Scale Package, Enterprise Package, Marketplaces
This API endpoint enables the removal of a registered webhook from the system using its unique ID. This ensures you can effectively manage and clean up webhook configurations that are no longer needed.
Request Parameters:
