Create Webhook

This API is used to create webhooks.

Endpoint Information

Property Value
URL {{APP_URL}}/api/v1/webhooks
HTTP Method POST
Content Type application/json
Authentication APIKEY header

Request Parameters

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.

SecurityData Content

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.

Example Usage

API Request

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
}

API Response

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
    }
}

Error Responses

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."
        }
    ]
}