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 has started",
                "location": "Your package may not have been sent 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:

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	Info received	8
package.in_transit	In transit	3
package.delivered	Available for pickup	4
package.handed	Delivered	5
package.delivery_failed	Exception	6, 7