Веб-страница + API

Вы создаёте сессию через API, а пользователь проходит процесс на нашей странице. Результат приходит вам через вебхук.

Схема работы

sequenceDiagram
    participant S as Ваш сервер
    participant D as DEBEX API
    participant U as Пользователь

    S->>D: POST /api/Sessions/start
    D-->>S: session_id, session_url
    S->>U: Редирект на session_url
    U->>D: Проходит шаги процесса
    D-->>S: Вебхук: session_completed (cookies)

Шаг 1. Получить список процессов

curl https://sessions-api.explorer.debex.ru/api/Flows

[
  {
    "id": "b3f70e2e-ed61-4145-a2ed-f69a459a8934",
    "name": "mos.ru",
    "description": "Авторизация на портале mos.ru"
  }
]

Альтернатива: направить пользователя на страницу создания сессии

Вместо создания сессии по API можно отправить пользователя на веб-клиент с предвыбранным процессом:

https://sessions.explorer.debex.ru/sessions/new?flowId={ID_ПРОЦЕССА}

Параметр	Описание
`flowId`	ID процесса — будет автоматически выбран в форме

Шаг 2. Создать сессию

curl -X POST https://sessions-api.explorer.debex.ru/api/Sessions/start \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "b3f70e2e-ed61-4145-a2ed-f69a459a8934",
    "webhook_url": "https://your-server.com/webhook",
    "webhook_events": ["session_completed", "session_failed"]
  }'

Параметры запроса:

Поле	Тип	Обязательное	Описание
`flow_id`	UUID	да	ID процесса
`webhook_url`	string	нет	URL для отправки событий (должен быть `https://`)
`webhook_events`	string[]	нет	Список событий: `session_started`, `session_completed`, `session_failed`, `step_changed`, `session_restarted`

Ответ:

{
  "session_id": "a1b2c3d4-...",
  "token": "eyJhbGciOi...",
  "session_url": "https://sessions.explorer.debex.ru/session?token=eyJhbGciOi...",
  "webhook_secret": "base64-encoded-secret",
  "flow_name": "mos.ru",
  "step_name": "Загрузка...",
  "elements": [],
  "is_completed": false,
  "expires_in_seconds": 300
}

Сохраните webhook_secret

webhook_secret возвращается только при создании сессии. Сохраните его — он нужен для верификации входящих вебхуков.

Шаг 3. Перенаправить пользователя

Отдайте пользователю ссылку из поля session_url. На этой странице он увидит интерфейс для прохождения процесса — формы ввода, OTP-коды и т.д.

Шаг 4. Получить вебхук

После успешного прохождения всех шагов на ваш webhook_url придёт POST-запрос:

{
  "event": "session_completed",
  "payload": {
    "session_id": "a1b2c3d4-...",
    "flow_name": "mos.ru",
    "is_completed": true,
    "cookies": [
      {
        "name": "auth_token",
        "value": "abc123...",
        "domain": ".mos.ru",
        "path": "/",
        "expires": 1735689600,
        "http_only": true,
        "secure": true,
        "same_site": "Lax"
      }
    ]
  },
  "timestamp": "2025-04-01T12:00:00Z"
}

Заголовки вебхука

Заголовок	Описание
`X-Webhook-Signature`	HMAC-SHA256 подпись тела запроса: `sha256={hex}`
`X-Webhook-Event`	Название события, например `SessionCompleted`

Верификация подписи

import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

using System.Security.Cryptography;

bool VerifyWebhook(byte[] body, string signature, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(body);
    var expected = "sha256=" + Convert.ToHexString(hash).ToLower();
    return expected == signature;
}

Доступные события

Событие	Когда
`session_started`	Сессия создана, первый шаг определён
`session_completed`	Процесс завершён успешно, cookies доступны
`session_failed`	Ошибка или таймаут
`step_changed`	Переход к следующему шагу
`session_restarted`	Пользователь перезапустил сессию