Webhooks | business.pkge.net - API для отслеживания

Вы можете настроить вебхуки для того, чтобы получать на свой сервер уведомления с информацией о различных событиях, например, об обновлении статусов посылок.

Создание и настройка конечных точек вебхука

Перейдите в раздел Webhooks в личном кабинете, добавьте конечную точку, вписав ее URL и выбрав необходимые события, которые будут на нее отправлены в дальнейшем. Максимальное количество добавляемых конечных точек - 5.

Обработка событий

Запросы вебхука отправляются на ваш сервер методом POST, тело запроса приходит в формате JSON.

Пример объекта события вебхука:

        
{
    "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": "Получение статуса...",
        "status": -1,
        "checkpoints": [
            {
                "id": "",
                "date": "2021-07-06T13:46:25+03:00",
                "title": "Начато отслеживание",
                "location": "Скорее всего, посылка еще не отправлена",
                "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": []
    }
}

Описание объекта:

Свойство	Тип	Описание
id	String	Уникальный идентификатор отправленного события
type	String	Тип отправленного события. Полный список событий смотрите в разделе «Типы событий»
timestamp	Int	Время отправки события (UNIX timestamp)
payload	Object	Объект с подробной информацией о событии. Например, актуальный на момент отправки уведомления объект Package. Подробности смотрите в разделе «Типы событий»

Проверка подлинности запроса

Во всех запросах событий вебхуков, отправляемых на вашу конечную точку, присутствует заголовок с подписью запроса:

Pkge-Webhook-Signature

В этом заголовке передается кодированный в Base64 хэш (SHA256 HMAC) тела отправленного запроса, в качестве секретного ключа используется ваш Webhook secret для конечной точки.

Т.к. ваша конечная точка открыта для всего интернета, единственным способом убедиться в том, что запрос действительно пришел от нас, является проверка подписи запроса.

Вы можете сделать это либо вручную...

Пример метода для проверки подписи на языке PHP:

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

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

...либо используя наш SDK

Пример использования PHP SDK для проверки подписи:

        $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());
}

Повторные попытки отправки уведомлений

В том случае, если после отправки уведомления о событии ваш сервер вернет ответ с HTTP-кодом состояния >= 400, уведомление будет отправлено повторно с экспоненциальной задержкой, максимум до 10 раз.

Номер попытки отправки	Задержка перед отправкой (сек.)	Общая задержка после первой попытки (сек.)
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

Типы событий

События обновления статуса посылки, полный список статусов посылки смотрите здесь. Ниже в последней колонке в таблице приведены идентификаторы статусов, которые относятся к событию.

Идентификатор	Описание	Статусы посылки
package.info_received	Информация о посылке получена	8
package.in_transit	Посылка доставляется	3
package.delivered	Посылка ожидает вручения	4
package.handed	Посылка доставлена	5
package.delivery_failed	Ошибка доставки	6, 7