Webhook — это новый сервис в iSpring Learn. Теперь можно получать уведомления об интересующих событиях в формате POST запроса по HTTP. Больше не нужно отправлять запросы в API, достаточно отследить изменения. Для этого нужно подписаться на интересующие события и иметь сервис, который будет обрабатывать уведомления.
Суть и шаги интеграции:
- Пользователь регистрирует подписчика, указывая URL на который будут в будущем приходит сообщения. Для одного аккаунта может быть несколько подписчиков.
POST /webhook/register - Пользователь подтверждает URL, отправив на него код подтверждения. После получения кода на указанный URL пользователь подтверждает URL
POST /webhook/code/send
POST /webhook/confirm
С этого момента интеграцию, можно считать активной - Подписчик создается активным и может сразу получать сообщения. При желании подписчика можно выключить и включить обратно.
POST /webhook/disable
POST /webhook/enable - Подписчика можно удалить навсегда
POST /webhook/remove - Настройки подписчика можно изменить. Если меняется URL, его нужно снова подтверждать отправкой кода.
POST /webhook/settings/change - Пользователь может подписать подписчика на предложенные события Learn. В рамках одного аккаунта разные подписчики могут быть подписаны на разные события. Но один подписчик может быть подписан только на событие одного типа
POST /webhook/subscribe - Пользователь может отписать подписчика от подписки.
POST /webhook/unsubscribe - Пользователь может получить список подписок подписчика и информацию о подписчике
GET /webhook/subscription/list
GET /webhook/subscriber/info
Отправка событий
Все события отправляются последовательно. Webhook ожидает некоторое время и отправляет события списком. В список объединяются только подряд идущие события одного типа. Если встретится событие другого типа, то последовательность будет прервана и начнёт накапливаться новая последовательность.
Сервис подписчика должен возвращать 200 код при получении, все другие коды будут считаться неудачей и будет запущен процесс повторной отправки
Повторная отправка
При неудачной отправке сервис будет пытаться сделать повторную отправку. Делать это он будет в течение суток. Во время ожидания новой попытки, события которые произошли будут продолжать копиться. При успешной повторной попытке все события, которые накопились за время пока сервис подписчика был недоступен отправятся подряд.
Если за сутки не удалось доставить сообщения, то статус подтверждения callbackURL перейдёт в неподтверждённый. И его снова нужно будет подтвердить. Все события, накопленные за время ретраев в таком случае будут потеряны.
Подпись
Для проверки источника сообщений, webhook может подписывать запросы. Для этого используется настройка secret. Если такая настройка была добавлена, то каждый запрос, отправляемый webhook, будет иметь заголовок X-Hub-Signature.
Содержимое формируется следующим образом: body отправляемого запроса конкатенируется с secret и затем полученная строка хэшируется алгоритмом SHA-256. Этот хэш и является содержимым заголовка.