Вебхуки

Вебхуки позволяют получать HTTP push-уведомления от платформы Verigram каждый раз, когда происходит какое-либо событие. Это позволяет создавать интеграции, реагирующие на изменения в реальном времени, без необходимости регулярно опрашивать API.

На данный момент поддерживаются следующие события:

• завершение сервиса в пайплайне Flow: если для прохождения сервиса во Flow потребовались повторы, вы получите уведомление о каждой попытке

• завершение всего Flow или его неактивность

Как работают вебхуки

Отправка вебхука (webhook push) представляет собой HTTP-запрос методом POST, отправленный на выбранный вами URL-адрес. Платформа Verigram автоматически инициирует отправку при наступлении события. Примеры содержимого (payload) можно посмотреть в разделе «Примеры сообщений».

Ваш обработчик вебхуков должен:

• быть публично доступным HTTPS URL-адресом

• возвращать ответ со статус-кодом 200 или 201

• возвращать ответ в течение 30 секунд

Если сообщение не удается доставить по указанному URL-адресу, сервис попытается повторно отправить запрос несколько раз в течение 3 минут. Повторные попытки выполняются при получении HTTP-статус-кодов 4xx и 5xx.

Создание вебхука

Существует два способа создания вебхука:

• с помощью консоли клиента (Client Console)

• с помощью API

Для создания вебхука в Консоли клиента перейдите в раздел «Settings», а затем во вкладку «Webhooks». Выберите сервис из списка, введите URL, на который необходимо отправлять уведомления, и нажмите кнопку «Add webhook». Для получения уведомления о завершении всего Flow выберите в списке сервисов значение Flow End.

Для создания вебхука через API обратитесь к спецификации API.

Верификация вебхуков

Начиная с версии API 2.1.0 (значение заголовка запроса X-Verigram-Api-Version, с помощью которого была создана сессия или флоу), вебхуки подписываются с использованием активного секретного ключа PROD, созданного последним. Если активных ключей PROD нет, используется активный секретный ключ TEST, созданный последним.

Примечания:

• Выбор секретного ключа. Секретный ключ выбирается в момент постановки вебхука в очередь. Вебхуки, которые уже находятся в очереди или отправляются повторно (в течение 3 минут), продолжают использовать секретный ключ, выбранный в момент постановки в очередь, даже если за это время вы создали новый ключ или деактивировали старый.

• Ротация ключей. После создания нового секретного ключа PROD новые вебхуки подписываются с использованием этого ключа. Чтобы не отклонять вебхуки, которые ещё находятся в процессе доставки, настройте принимающую сторону так, чтобы она в течение нескольких минут после ротации принимала подписи, соответствующие как предыдущему, так и новому секретному ключу. После этого старый ключ можно удалить из конфигурации принимающей стороны.

Чтобы подтвердить подлинность уведомления, самостоятельно вычислите HMAC на своей стороне тем же методом и сравните полученное значение со значением заголовка X-Verigram-Hmac-SHA256.

Пример Python

import hashlib
import hmac

api_secret = "secret"   # get it from Client Console
received_hmac = request.headers.get("X-Verigram-Hmac-SHA256")

calculated_hmac = hmac.new(
    api_secret.encode("utf-8"),
    msg=request.data, 
    digestmod=hashlib.sha256
).hexdigest()

if calculated_hmac == received_hmac:
    print("Hmac is valid!")
else:
    print("Hmac is not valid!")

Примеры сообщений