Webhook — новый сервис в iSpring Port. Теперь можно получать уведомления о событиях в формате 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 - Пользователь может подписать подписчика на предложенные события iSpring Port. В рамках одного аккаунта разные подписчики могут быть подписаны на разные события. Один подписчик может быть подписан только на событие одного типа.
Используйте запрос: 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. Хэш является содержимым заголовка.