Webhook

Modified on Wed, 1 Oct at 8:39 PM

# 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. ``` json { "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: ``` json { "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: ``` json { "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/webhook

Example 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/webhook

Request 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/webhook

Example 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/webhook

Request 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: |