Shopify App

Webhooks

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

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

Перейдите в раздел 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