Вебхуки
Вебхуки предоставляют возможность получать обновления по интересующим темам, как только они произошли в системе ATI.SU.
Требования к вебхукам
Для того чтобы обеспечить безопасность и стабильную работу, есть несколько требований, которым должен удовлетворять вебхук:
- не является открытым и угадываемым, то есть третьи лица не должны иметь возможности узнать о его существовании;
- если используется DNS-имя, оно должно разрешаться в публичный1 IPv4 адрес;
- если используется IP-адрес, он должен быть публичным1 IPv4 адресом;
- доступен по протоколу HTTPS;
- уникален на каждую подписку.
Рекомендации по реализации
1. Время ответа
На ответ вебхуку дается 20 секунд, поэтому рекомендуется реализовывать его таким образом, чтобы ответ означал факт получения сообщения, а не его обработки.
2. Уникальность
Во избежание смешивания данных разных пользователей, рекомендуется для каждой подписки иметь уникальный URL.
3. TLS
Сообщения могут содержать закрытую информацию, поэтому отправка их в незашифрованном виде недопустима. Если у вас нет возможности использовать доверенный сертификат, напишите на почту api@ati.su.
Использование API
Для существования вебхука необходимы два метода по одному URL. Первый (GET) отвечает за управление состоянием, а второй (POST) — за передачу сообщений.
Создание вебхука
Создание вебхука происходит в два этапа: отправка запроса на создание и верификация.
Отправка запроса на создание
При отправке запроса на создание необходимо выбрать тему подписки.
Параметр callback должен содержать URL вебхука. В URL допустимы параметры запроса, которые будут переданы при вызове вебхука. Параметры запроса можно использовать, например, для привязки вебхука к пользователю: https://example.org/webhook?userId=00000000.
В ответе содержится заголовок Location с URL GET-метода проверки состояния созданного вебхука.
Верификация
После отправки запроса на создание, вебхук проходит верификацию. Вызывается GET метод по URL вебхука с параметрами challenge и topic, а также параметрами указанными при создании.
GET /webhook?status=verification&verification_status=progress&topic=orders&challenge=608b672ed0a5aaecc2d42488 HTTP/1.1 Host: example.org Accept: application/json
Вебхук должен ответить в течение
20
секунд на верификационный запрос JSON-строкой с содержимым параметра challenge.
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Content-Length: 26 "608b672ed0a5aaecc2d42488"
Как только ответ будет получен, отправится оповещение о смене состояния. После успешной верификации, отключите логику обработки параметра challenge для данного вебхука, чтобы избежать ошибок.
Если верификация провалилась, узнать причину можно с помощью метода проверки состояния вебхука. Вебхук будет находиться в состоянии verification.
Проверка состояния вебхука
Проверка состояния одного Веб-хука
Проверка состояния нескольких Веб-хуков
Оповещения о смене состояния вебхука
GET-метод по URL вебхука используется также для оповещений о смене его (вебхука) состояния. Во все вызовы передается парметр topic, обозначающий тему подписки.
| Событие | Параметры | Описание |
|---|---|---|
| Провал верификации | status: verificationverification_status: failed |
Проблемы с верификацией. |
| Провал отправки | distribution_status: failedsince: YYYY-MM-DDThh:mm:ss |
Проблемы с отправкой сообщения. В параметре since указана дата первой проваленной отправки. |
| Провал повторной отправки | distribution_status: failed_retryfailed_count: число |
Проблемы с повторной отправкой сообщений. В параметре failed_count указано количество повторно отправляемых сообщений. |
| Остальные изменения состояния вебхука | status: одно из значений поля status |
Оповещение о смене статуса не ожидает ответа.
Получение сообщений
При возникновении события, вызывается POST метод вебхука с параметром topic. В теле запроса передается одна или несколько обновленных сущностей (параметр entities[].entity) и другие параметры события.
Соответствие порядка возникновения событий и отправки сообщений не гарантируется. Поэтому, при получении сообщения, необходимо сравнивать параметр action_date текущего и предыдущего сообщений.
Запрос с отправляемыми сообщениями
Тема
Сообщения
Id отправляемой сущности
Дата события
Отправляемая сущность
Является ли отправка повторной
POST /webhook?topic=orders HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 208
{"topic": "orders", "entities": [{"entity_id": "4ea8c372-9510-4880-a80d-fb9ac19129cf", "action_date": "2021-04-30T05:12:41.687Z", "entity": {"id": "4ea8c372-9510-4880-a80d-fb9ac19129cf"}}], "is_retry": false}
Ожидается ответ с кодом 2xx (Successful)2 на протяжении 20 секунд. В ином случае отправка помечается проваленной, и отправляется оповещение об изменении состояния вебхука.
Для временной приостановки получения сообщений, можно использовать ответ 429 (Too Many Requests)3 с заголовком Retry-After4. Приостановка возможна не более чем на 1 день.
Если был получен ответ 410 (Gone)5, вебхук удаляется без возможности восстановления.
Повторные отправки
Как только вебхук успешно примет сообщение, будет предпринята попытка повторно отправить сообщения, отправка которых провалилась ранее. Отличить повторную отправку от первоначальной можно по значению true в заголовке ATI-Is-Retry запроса. В случае провала повторной отправки, она будет отложена до успешного получения вебхуком нового сообщения.
Если отправки проваливаются на протяжении 4 дней, вебхук деактивируется. Возобновление его работы возможно только через повторное создание.
До тех пор, пока вебхук не удален, можно получить его проваленные отправки.
Удаление вебхука
При удалении вебхука, прекращается отправка сообщений в него, а также удаляются его проваленные отправки.