Щоб отримувати оновлення в режимі реального часу про сутності (зміни та фіскальні чеки), вам слід правильно налаштувати webhook.
У цій інструкції наведено основні методи роботи з webhook.
Указана адреса повинна приймати POST запити із указаною в документації схемою та повертати статус-код 200, у разі якщо статус-код буде >= 400 або час очікування відповіді більше 10 секунд запит буде повторюватись протягом 4-х годин з експоненційним інтервалом (backoff-retry, збільшення від 1 секунди до 30 хвилин).
Даним методом встановлюється URL адреса куди при фіскалізації чеків, відкритті та закритті змін а також службових внесеннях та вилученнях буде надіслано POST запити з відповідною інформацією. Налаштування зберігаються для кожної каси окремо.
Під час встановлення налаштувань сервером CheckBox генерується секретний ключ та повертається у відповіді на даний метод, за допомогою цього ключа можна перевірити чи дійсно запит виконується серверами CheckBox. Під час виконання виклику вебхуків тіло запиту хешується за допомогою алгоритму:
encodeBase64(
HmacSHA256(
secret_key,
getBytesUTF-8(
request_body
)
)
)
· encodeBase64 - функція перетворення бінарних даних в Base64 формат
· HmacSHA256 - функція створення хешу підпису даних
· getBytesUTF-8 - функція перетворення рядка в бінарне представлення (в кодуванні UTF-8)
· request_body - тіло запиту
· secret_key - секретний ключ
з використанням ключа та записується до заголовку x-request-signature, таким чином на стороні де отримується запит можна перевірити дійсність даних за тим же алгоритмом.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення)>
Authorization: <токен авторизації>
Content-Type: application/json
{
"url": "<URL-адреса, куди будуть відправлятись POST запити>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/webhook' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: d6b79c938aff6bebc8d11111' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "url": "https://webhook.site//b1992f12-6536-4c3b-a74d-f2fb5f511111"}'
{
"url": "https://webhook.site/b1992f12-6536-4c3b-a74d-f2fb5f511111",
"last_error_date": null,
"last_error_message": null,
"created_at": "2023-10-22T16:16:03.658314+00:00",
"updated_at": null,
"key": "tnX7jL6CZDdiNkVGuH0KukAl_ND11111"
}
url - URL-адреса, куди будуть відправлятись POST запити
last_error_date - дата та час останньої помилки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
last_error_message - опис останньої помилки
created_at - дата та час встановлення вебхука у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
updated_at - дата та час останнього оновлення вебхука у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
key - секретний ключ інтеграції, за допомогою якого можна перевірити, чи дійсно POST запити виконуються серверами checkbox - повертається тільки при встановленні вебхуку!
Даним методом можна перевірити стан налаштувань вебхуків за обраною касою.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення)>
Authorization: <токен авторизації>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/webhook' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: d6b79c938aff6bebc8d11111' \ -H 'Authorization: Bearer token'
{
"url": "https://webhook.site/b1992f12-6536-4c3b-a74d-f2fb5f511111",
"last_error_date": null,
"last_error_message": null,
"created_at": "2023-10-22T16:16:03.658314+00:00",
"updated_at": null
}
{
параметри відповіді співпадають із параметрами відповіді методу POST /api/v1/webhook (окрім параметра "key", який повертається тільки при встановленні вебхуку)
}
Метод видаляє налаштування вебхуків. Повторне виконання методу завжди буде повертати відповідь "ok": true.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення)>
Authorization: <токен авторизації>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'DELETE' \ 'https://api.checkbox.ua/api/v1/webhook' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: d6b79c938aff6bebc8d11111' \ -H 'Authorization: Bearer token'
{
"ok": true
}
ok - true/false, результат успіху операції.