This API is used to create webhooks.
| Property | Value |
|---|---|
| URL | {{APP_URL}}/api/v1/webhooks |
| HTTP Method | POST |
| Content Type | application/json |
| Authentication | APIKEY header |
| Parameter Name | Parameter Type | Required | Description |
|---|---|---|---|
description |
String (MAX 255) | REQUIRED | Webhook description |
endpoint |
String (MAX 255) | REQUIRED | Webhook URL |
subscribedEvent |
String (MAX 255) | REQUIRED | Subscribed event. Values are listed on the Event Types page |
securityType |
String (MAX 255) | REQUIRED | Authentication type |
dataType |
String (MAX 255) | REQUIRED | Data type |
data |
String (MAX 255) | OPTIONAL | Data |
requestType |
String (MAX 255) | OPTIONAL | The name of the SOAP method to call when dataType is SOAP |
securityData |
Array | Depends on securityType |
Authentication data. Its content is explained in the table below |
status |
Integer | REQUIRED | Status |
Only one active webhook per event can be defined for each customer. To receive package-level notifications (package.status.updated, package.size.updated), create separate webhook records for these events; your existing consignment.* webhooks keep working unchanged.
The content of securityData changes with the securityType value:
securityType |
securityData content |
Description |
|---|---|---|
none |
Not needed | No authentication is done. |
header |
[{"headerKey": "...", "headerValue": "..."}] |
Each item is sent as a header. You can define more than one header. |
basic |
{"username": "...", "password": "..."} |
HTTP Basic authentication is used. |
bearer |
{"tokenUrl": "...", "tokenKey": "...", "data": {...}} |
The data content is sent to tokenUrl with POST. The token is read from the response field given in tokenKey (use a dot for nested fields, for example data.token). The token is sent in the Authorization: Bearer header. |
Below is an example JSON data for the API request.
POST {{APP_URL}}/api/v1/webhooks
Content-Type: application/json
Authorization: APIKEY {{APIKEY}}
{
"description": "My Tracking",
"endpoint": "https://myapi.com/status",
"subscribedEvent": "consignment.status.updated",
"securityType": "header",
"dataType": "JSON",
"data": "",
"securityData": [
{
"headerKey": "Authorization",
"headerValue": "123"
}
],
"status": 1
}
On a successful request, the API returns a response like the following with the HTTP 201 status code:
{
"status": true,
"message": "Webhook created successfully",
"data": {
"id": 123,
"customer": {
"id": 456
},
"description": "My Tracking",
"requestType": null,
"dataType": "JSON",
"endpoint": "https://myapi.com/status",
"data": "",
"subscribedEvent": "consignment.status.updated",
"securityType": "header",
"securityData": [
{
"headerKey": "Authorization",
"headerValue": "123"
}
],
"status": 1
}
}
If the API request fails, the API will return an error response like the following:
{
"status": false,
"errors": [
{
"message": "Invalid endpoint URL. Please check the URL and try again."
}
]
}