Webhooks

You can configure webhooks to receive notifications to your server with information about various events, such as package status updates.

Creating and configuring webhook endpoints

Go to the Webhooks section in your personal account and add an endpoint by entering its URL and selecting the events that will be sent to it in the future. The maximum number of endpoints added is 5.

Processing events

Webhook requests are sent to your server by the POST method. The request body is received in JSON format.

Example of a webhook event object:

        
{
    "id": "f4383e6e-2af1-4992-ba19-afe53c07b3db",
    "type": "package.info_received",
    "timestamp": 1633609499,
    "payload": {
        "created_at": "2021-07-06T13:46:25+03:00",
        "updated_at": "2021-07-06T13:46:25+03:00",
        "started_tracking_at": "2021-07-06T13:46:25+03:00",
        "track_number": "UA937578848US",
        "origin": null,
        "destination": null,
        "last_status": "Receiving status...",
        "status": -1,
        "checkpoints": [
            {
                "id": "",
                "date": "2021-07-06T13:46:25+03:00",
                "title": "Tracking started",
                "location": "The package most likely isn't shipped yet",
                "latitude": null,
                "longitude": null,
                "courier_id": null
            }
        ],
        "last_status_date": "2021-07-06T13:46:25+03:00",
        "est_delivery_date_from": null,
        "est_delivery_date_to": null,
        "extra_track_numbers": [],
        "hash": "f25370e9",
        "consolidated_track_number": null,
        "consolidation_date": null,
        "destination_country_code": "ru",
        "updating": false,
        "last_tracking_date": null,
        "days_on_way": 1,
        "weight": null,
        "extra_info": [],
        "couriers_ids": [
            1,
            4,
            10,
            366
        ],
        "courier_id": null,
        "info": []
    }
}
        
    

Object description:

Property Type Description
id String Unique identifier of the sent event
type String The type of sent event. For a complete list of events, see the «Event types» section
timestamp Int Event sending time (UNIX timestamp)
payload Object An object with detailed information about the event. For example, the Package object was relevant at the time the notification was sent. See «Event types» for details

Request authentication

All webhook event requests sent to your endpoint have a header with a request signature:

Pkge-Webhook-Signature

This header transmits the Base64-encoded hash (SHA256 HMAC) of the sent request body using your Webhook secret as the secret key for the endpoint.

Since your endpoint is open to the entire Internet, the only way to ensure that the request came from us is to verify the request signature.

You can either do it manually...

Example of a method for signature verification in PHP:

        function isRequestSignatureValid($requestBody, $requestSignature, $webhookSecret) {
    $hash = hash_hmac('SHA256', $requestBody, $webhookSecret, true)

    return base64_decode($requestSignature) === $hash;
}
    

...or using our SDK

Example of usage of PHP SDK for signature verification:

        $webhookSecret = 'YOUR_WEBHOOK_SECRET';

$webhook = new \Pkge\Webhook($webhookSecret);

try {
    $event = $webhook->handleEvent(
        file_get_contents("php://input"),
        $_SERVER['HTTP_PKGE_WEBHOOK_SIGNATURE']
    );
} catch (\Pkge\Exceptions\WebhookSignatureException $e) {
    die ($e->getMessage());
}
        
    

Repeated attempts to send notifications

If your server returns a response with an HTTP status code >= 400 on sending an event notification, the notification will be resent with an exponential delay up to a maximum of 10 times.

Number of attempt send Delay before sending (seconds) Total delay after the first attempt (seconds)
1 0 0
2 30 30
3 120 150
4 270 420
5 480 900
6 750 1650
7 1080 2730
8 1470 4200
9 1920 6120
10 2430 8550

Event types

Package status update events, check here for a complete list of package statuses. The status identifiers related to the event are given in the last column in the table.

Identifier Description Package statuses
package.info_received Information has been received 8
package.in_transit Package in transit 3
package.delivered Package is awaiting delivery 4
package.handed Package delivered 5
package.delivery_failed Package delivery error 6, 7