Перейти к содержанию

Webhooks

Webhooks отправляют на endpoint клиентской системы уведомления о ходе сессии. Они позволяют реагировать на завершение Workflow без постоянного опроса API.

Webhook является server-to-server запросом. Используйте его как основной сигнал для обновления состояния заявки, а затем при необходимости запросите актуальный результат сессии.

Настройка

В личном кабинете откройте настройки нужного Workflow и добавьте URL получателя в разделе Webhooks. Для одного Workflow можно настроить до пяти URL, изменить или удалить существующие адреса и отправить тестовое событие.

Endpoint должен быть доступен по HTTPS и принимать POST с JSON-телом.

Типы событий

Событие Когда отправляется Содержимое data
flow.start Пользователь начал сессию Список технологий Workflow
flow.end Сессия завершилась Итоговый результат сессии
technology.start Началось выполнение технологии Код и название технологии
technology.end Технология завершилась Результат соответствующей технологии

Общая структура

Каждое событие содержит общий envelope:

Поле Тип Описание
id string Уникальный идентификатор события
event string Тип события
session_id string Идентификатор сессии Workflow
created number Время создания события в формате Unix timestamp
success boolean Признак успешности события
flow_name string Название Workflow
metadata object \| null Метаданные, переданные при создании сессии
data object Данные, зависящие от типа события

flow.start

Событие сообщает, что пользователь начал прохождение Workflow:

{
  "id": "d45aef15-8949-4812-b873-650615d51d1a",
  "event": "flow.start",
  "session_id": "70f5e424-07a9-4393-ba31-7f3de8681a72",
  "created": 1734597331,
  "success": true,
  "flow_name": "Liveness Head Position Flow",
  "metadata": {},
  "data": {
    "technologies": ["LDHP"]
  }
}

flow.end

Событие flow.end сообщает об окончании сессии и содержит результат в data.session_result.

Успешное завершение:

{
  "id": "5665f3c1-adce-4fe7-85f3-1e40e38cc0b7",
  "event": "flow.end",
  "session_id": "70f5e424-07a9-4393-ba31-7f3de8681a72",
  "created": 1734597391,
  "success": true,
  "flow_name": "Liveness Head Position Flow",
  "metadata": {},
  "data": {
    "session_result": {
      "status": "FINISHED",
      "session_id": "70f5e424-07a9-4393-ba31-7f3de8681a72",
      "technologies": [
        {
          "code": "LDHP",
          "name": "Liveness Head Position",
          "description": "Detect liveness by photo and head position"
        }
      ],
      "liveness_result": {
        "result": true,
        "eye_closed": false,
        "prediction": "0.9980",
        "face_center": true,
        "face_direction": "forward"
      },
      "flow_session_result": true
    }
  }
}

Неуспешное завершение:

{
  "id": "2d891060-3b14-4920-ad0f-d21b70a9c33c",
  "event": "flow.end",
  "session_id": "3efb1a25-5d94-493d-99cf-043881909820",
  "created": 1734597876,
  "success": false,
  "flow_name": "Liveness Head Position Flow",
  "metadata": {},
  "data": {
    "session_result": {
      "status": "FAILED",
      "session_id": "3efb1a25-5d94-493d-99cf-043881909820",
      "technologies": [
        {
          "code": "LDHP",
          "name": "Liveness Head Position",
          "description": "Detect liveness by photo and head position"
        }
      ],
      "liveness_result": {
        "result": false,
        "failure_reason": {
          "type": "CALC_RESULT",
          "detail": "Low overall prediction"
        }
      },
      "flow_session_result": false
    }
  }
}

Значения failure_reason описаны в справочнике причин отказа.

События технологий

technology.start содержит код и название начавшейся технологии:

{
  "id": "8c44f37b-6040-40ed-b391-682a3b29dc2b",
  "event": "technology.start",
  "session_id": "70f5e424-07a9-4393-ba31-7f3de8681a72",
  "created": 1734597343,
  "success": true,
  "flow_name": "Liveness Head Position Flow",
  "metadata": {},
  "data": {
    "technology_code": "LDHP",
    "technology_name": "Liveness Head Position"
  }
}

technology.end содержит блок результата завершившейся технологии:

{
  "id": "35bef608-a327-4b46-a4e0-cf1a8c6e0703",
  "event": "technology.end",
  "session_id": "70f5e424-07a9-4393-ba31-7f3de8681a72",
  "created": 1734597388,
  "success": true,
  "flow_name": "Liveness Head Position Flow",
  "metadata": {},
  "data": {
    "liveness_result": {
      "result": true,
      "eye_closed": false,
      "prediction": "0.9980",
      "face_center": true,
      "face_direction": "forward",
      "failure_reason": null
    }
  }
}

Название блока и его поля зависят от технологии. Общие блоки результата перечислены на странице получения результата.

Проверка endpoint через cURL

Следующий запрос имитирует доставку события на ваш endpoint:

curl --request POST \
  --url 'https://example.com/webhooks/biometric' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "d45aef15-8949-4812-b873-650615d51d1a",
    "event": "flow.start",
    "session_id": "70f5e424-07a9-4393-ba31-7f3de8681a72",
    "created": 1734597331,
    "success": true,
    "flow_name": "Liveness Head Position Flow",
    "metadata": {},
    "data": {
      "technologies": ["LDHP"]
    }
  }'

Надёжная обработка

  • Верните успешный ответ 2xx после надёжной записи события.
  • Обрабатывайте события идемпотентно: повторная доставка одного id не должна повторно запускать бизнес-операцию.
  • Связывайте событие со своей заявкой по session_id.
  • Не полагайтесь на порядок получения разных HTTP-запросов.
  • Если обработка занимает много времени, сохраните событие и продолжите работу асинхронно после ответа.
  • Используйте flow.end как сигнал завершения, а при необходимости получайте актуальное состояние через API результата.