How to Create a Webhook

Modified on Sat, 1 Feb at 9:14 PM

Webhooks are a powerful tool that allows OTO to send updates to your system automatically whenever certain events occur, such as order status changes or shipment errors. Follow this guide to set up a webhook using the API.

Instructions

Step 1: API Endpoint

The method and endpoint for creating a webhook is: POST https://api.tryoto.com/rest/v2/webhook
This endpoint allows you to define the webhook settings, including the URL, authorization details, and the type of events you want to track.

Step 2: Authorization

Include a valid Bearer Token in the request header.

Step 3: Request Body Parameters

Provide the following fields in the request body:

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	it is sent in `Authorization` header
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.

Step 4: Example Request

Here’s an example of a request to create a webhook:

curl --location 'https://api.tryoto.com/rest/v2/webhook' \
--data '{
    "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":"orderStatus"
}'

Step 5: Example Response

A successful response will look like this:

{
  "success": true,
  "id": "59",
  "message": "webhook has been created"
}

There are also endpoints for retrieving, updating and deleting the created webhooks, kindly check our API Documentation for reference.