Вебхуки

Вебхуки Exode — это исходящие HTTP-уведомления: при наступлении события в платформе (регистрация, оплата, прогресс по курсу и т.д.) Exode отправляет POST-запрос на ваш URL с данными события.

Доставка идёт почти в реальном времени через очередь с повторными попытками. Приёмник должен быть идемпотентным и быстро отвечать кодом 200, 201 или 202 (таймаут ответа — 15 секунд).

Как это работает

Событие фиксируется

Ядро Exode генерирует доменное событие (например, PaymentCompleted) с таймстемпом и параметрами инициатора.

Поиск активных эндпоинтов

Exode находит активные эндпоинты вашего продавца, подписанные на это событие. На одного продавца можно создать не более 5 эндпоинтов.

Сборка полезной нагрузки

Для события собираются связанные сущности (пользователь, платёж, доступ и т.д.), формируется data, единый idempotencyKey и timestamp. Лишние поля вырезаются по строгой схеме (allow-list).

Отправка с подписью и повторы

Тело отправляется POST-запросом с заголовком signature (HMAC-SHA256). Если приёмник не ответил 200/201/202, доставка повторяется с нарастающей задержкой — всего до 5 попыток.

Чтобы остановить доставку — переведите эндпоинт в active = false или удалите его.

Формат сообщения

Тело запроса — JSON-объект следующей структуры:

string

обязательно

Имя события. Одно из значений раздела «Поддерживаемые события».

string

обязательно

Момент возникновения события в формате ISO 8601 (UTC).

string

обязательно

Единый ключ события. Один и тот же ключ используется для всех эндпоинтов и сохраняется между повторными попытками. Используйте его для дедупликации.

object

обязательно

Полезная нагрузка с доменными сущностями. Состав зависит от события — см. ниже.

Структура тела

{
  "event": "PaymentCompleted",
  "timestamp": "2025-01-18T12:44:55.812Z",
  "idempotencyKey": "7qqQL3bE0o8R8d3X",
  "data": { /* depends on the event */ }
}

Заголовок подписи называется буквально signature (в нижнем регистре), а не X-Signature. Подпись считается от всего тела запроса, включая event, timestamp и idempotencyKey.

Проверка подписи

В каждом запросе передаётся заголовок signature — это HMAC-SHA256 (hex) от сырого тела запроса, подписанного секретным ключом вашего эндпоинта.

secretKey передаётся в HMAC как есть, как ASCII/UTF-8 строка из 64 символов. Несмотря на внешний вид, его не нужно декодировать из hex или base64. Результат подписи — строка из 64 hex-символов в нижнем регистре, без префикса sha256=.

import crypto from 'crypto';
import express from 'express';

const app = express();

// Important: use the raw body, not a re-serialized object
app.post('/webhooks/exode', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const received = req.header('signature') || '';

  const expected = crypto
    .createHmac('sha256', process.env.EXODE_WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

  if (!valid) {
    return res.status(401).send('invalid signature');
  }

  const payload = JSON.parse(rawBody);
  // TODO: deduplicate by payload.idempotencyKey and handle payload.data

  res.sendStatus(200);
});

<?php
$rawBody  = file_get_contents('php://input');
$received = $_SERVER['HTTP_SIGNATURE'] ?? '';
$secret   = getenv('EXODE_WEBHOOK_SECRET');

$expected = hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expected, $received)) {
  http_response_code(401);
  exit('invalid signature');
}

$payload = json_decode($rawBody, true);
// TODO: deduplicate by $payload['idempotencyKey'] and handle $payload['data']

http_response_code(200);

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post('/webhooks/exode')
def exode_webhook():
    raw_body = request.get_data()  # bytes, raw body
    received = request.headers.get('signature', '')
    secret = os.environ['EXODE_WEBHOOK_SECRET'].encode()

    expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, received):
        abort(401)

    payload = request.get_json()
    # TODO: deduplicate by payload['idempotencyKey'] and handle payload['data']
    return '', 200

Считайте HMAC именно от сырого тела запроса. Повторная сериализация JSON (с другим порядком полей, пробелами или экранированием Unicode) даст другую подпись.

Доставка и повторные попытки

Параметр	Значение
HTTP-метод	`POST`
Content-Type	`application/json`
Заголовок подписи	`signature` (HMAC-SHA256, hex)
Таймаут ответа	15 секунд
Успешные коды	`200`, `201`, `202`
Число попыток	до 5 (первая отправка + до 4 повторов)
Задержки между попытками	≈ 11 → 33 → 77 → 165 минут (последняя попытка — примерно через 4 ч 45 мин после первой)
Порядок доставки	не гарантируется
Дедупликация	по `idempotencyKey` на вашей стороне

Любой ответ, кроме 200/201/202, а также таймаут или сетевая ошибка считаются неуспехом и приводят к повторной попытке. После 5 неудачных попыток событие помечается как failed и больше не отправляется.

Автоотключение эндпоинта. Если эндпоинт не принимает события 14 дней подряд (за это время не было ни одной успешной доставки и его не включали вручную), Exode переводит его в active = false и уведомляет владельца продавца. Новые события на такой эндпоинт не отправляются, пока его снова не включат в кабинете.

Управление эндпоинтами

Эндпоинты вебхуков настраиваются в кабинете: Управление → Школа → Вебхуки (/manage/school/webhooks). Нужно право «Управление настройками школы» (SchoolManageSettings). Через SaaS API эндпоинты не управляются. Для каждого эндпоинта задаётся:

url — адрес приёмника (до 255 символов); используйте HTTPS;
events — список событий, на которые он подписан;
active — флаг активности (по умолчанию true);
note — произвольная заметка (до 255 символов);
secretKey — секрет для проверки подписи, генерируется автоматически при создании эндпоинта.

Где взять секрет для проверки подписи: secretKey создаётся вместе с эндпоинтом. В кабинете он копируется командой «Копировать подпись» — в меню строки эндпоинта или рядом с полем URL в его форме (несмотря на название, копируется именно секрет, а не готовая подпись). Сохраните его в переменных окружения вашего сервиса (в примерах выше — EXODE_WEBHOOK_SECRET). Если секрет не отображается — запросите его у поддержки.

Используйте отдельные эндпоинты для независимых систем — это изолирует сбои и позволяет управлять разными наборами событий. На одного продавца — максимум 5 эндпоинтов.

Тестовая отправка

Тестовая отправка из формы сохранённого эндпоинта подписывается его же secretKey. Формат тела, алгоритм и заголовок полностью совпадают с боевыми событиями, поэтому приёмнику не нужна отдельная ветка проверки для тестовых вебхуков.

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

Поддерживаемые события

Ниже — события, которые реально доставляются, и структура их поля data. Вложенные сущности (user, profile, course, payment и др.) описаны в справочнике объектов.

UserSignedUp — регистрация пользователя

Триггер: пользователь самостоятельно завершил регистрацию.data:

user — объект пользователя.
profile — карточка профиля (null, если не заполнена).
states.utmSignupParams — объект UTM-меток первичного визита (опционально).

UserAcquainted — завершён онбординг

Триггер: пользователь прошёл онбординг. Структура data идентична UserSignedUp (user, profile, states.utmSignupParams).

UserTgConnected — привязан Telegram

Триггер: пользователь связал аккаунт Telegram.data:

user — объект пользователя (с актуальным tgId).
profile — карточка профиля (опционально).
prevTgId — предыдущий tgId для отслеживания перепривязки (number | null).

UserCreatedViaLms — школа создала пользователя

Триггер: сотрудник школы создал нового пользователя — в кабинете (по одному или массовым импортом) или через API user/create и user/upsert (только когда upsert создаёт пользователя, а не обновляет существующего). Самостоятельная регистрация пользователя приходит отдельным событием UserSignedUp.data:

user — объект пользователя.
profile — карточка профиля (опционально).

CourseProgressChanged — изменился прогресс по уроку

Триггер: изменился статус урока у пользователя.data:

user — пользователь с профилем.
course — объект курса.
product — продукт курса (опционально).
access — доступ пользователя к продукту курса (опционально).
states.utmEnrollParams, states.utmSignupParams — UTM-метки записи и регистрации, см. UTM-атрибуция.
groups — массив групп пользователя в курсе (опционально).
status — новый статус урока из записи прогресса (опционально): NotStarted, OnTheory, OnPractice, OnReview, OnCorrection или Completed — расшифровка в courseProgress.
lessonId — ID урока (опционально).

CourseCompleted — курс завершён

Триггер: пользователь завершил курс.data:

user — пользователь с профилем.
course — объект курса.
product — продукт курса (опционально).
access — доступ пользователя (опционально).
states.utmEnrollParams, states.utmSignupParams — UTM-метки записи и регистрации, см. UTM-атрибуция.
groups — массив групп (опционально).

CourseLessonPracticeCompleted — пройдена практика

Триггер: пользователь завершил практическое задание урока.data:

user — пользователь с профилем.
course — курс (опционально).
lesson — урок (опционально).
practice — параметры практики (опционально).
attempt — попытка прохождения с баллами и статусом (опционально).
variantId — ID варианта (опционально).

PaymentCompleted — оплата прошла успешно

Триггер: платёж успешно завершён.data.payment — объект платежа с полным деревом: invoice (счёт), invoice.user (покупатель с профилем и школой), invoice.products (позиции с продуктом/курсом, ценой и скидкой), acquiring (эквайринг и провайдер, без секретов). Денежные поля — числа.Событие отправляется только при реальном списании денег: инициализация рекуррента (привязка карты, нулевой платёж со статусом BindingCompleted) вебхук не вызывает.

ProductEnrolledToFree — выдан бесплатный доступ

Триггер: пользователю выдан бесплатный доступ к продукту.data:

user — пользователь.
profile — карточка профиля (опционально).
access — объект доступа (опционально).
states.utmEnrollParams, states.utmSignupParams — UTM-метки записи и регистрации, см. UTM-атрибуция.
product — продукт (опционально).
course — курс (опционально).

ProductEnrolledViaLms — доступ выдан вручную (LMS)

Триггер: доступ к продукту выдан администратором/менеджером через LMS или API. Структура data идентична ProductEnrolledToFree (user, profile, access, product, course, states).

ProductEnrolledViaPayment — доступ выдан после оплаты

Триггер: доступ к продукту выдан после успешной оплаты. Структура data идентична ProductEnrolledToFree (user, profile, access, product, course, states).

ProductEnrolledByInviteLink — запись по ссылке-приглашению

Триггер: пользователь самостоятельно записался на курс по ссылке-приглашению.data: те же поля, что и у ProductEnrolledToFree (user, profile, access, product, course, states), плюс:

inviteLinkId — идентификатор ссылки, по которой пришёл пользователь (дублируется в access.meta.inviteLinkId).

При записи по ссылке отправляются два события: ProductEnrolledToFree и ProductEnrolledByInviteLink. Ссылка выдаёт доступ бесплатно, поэтому общий контур бесплатных зачислений срабатывает тоже — учитывайте это при подсчёте зачислений. Отличить запись по ссылке можно по наличию inviteLinkId.

CertificateIssued — выдан сертификат

Триггер: пользователю выдан сертификат за завершение курса. Событие приходит один раз на пару «пользователь + курс»: повторное завершение курса нового сертификата не создаёт.data:

user — пользователь с профилем.
course — объект курса.
product — продукт курса (опционально).
certificate — объект сертификата с публичной ссылкой link (открывается без авторизации), сроком действия и слепком данных на момент выдачи.

На события UserSignedIn, UserLoggedOut, UserJoinedByReferral, CourseLessonPracticeDetailedSent, CourseLessonPracticeAutoVerifySent, ProductRefundCompleted, ProductAccessSubscriptionEnding7Days и ProductAccessSubscriptionEnding1Day можно подписаться, но формальный контракт data для них ещё не зафиксирован — состав полезной нагрузки не гарантируется. Перед использованием сверьтесь с поддержкой.

UTM-атрибуция

UTM-метки приходят в трёх местах в зависимости от события:

Событие	Где искать UTM
`UserSignedUp`, `UserAcquainted`	`states.utmSignupParams` — метки визита, с которого пользователь зарегистрировался
`ProductEnrolledToFree`, `ProductEnrolledViaLms`, `ProductEnrolledViaPayment`, `ProductEnrolledByInviteLink`, `CourseProgressChanged`, `CourseCompleted`	`states.utmEnrollParams` — метки визита, с которого пользователь записался на продукт (дублируются в `access.meta.utmParams`); рядом `states.utmSignupParams` — метки регистрации
`PaymentCompleted`	`payment.invoice.meta.utmParams` — метки визита, с которого был создан счёт

Ключи объекта UTM: utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid, yclid, referrer, aff_id, sub_id, track_id (присутствуют только переданные). Если пользователь пришёл без меток, объект отсутствует или пуст.

Путь access.metaHistoryLogs[0].meta.utmParams, который использовали ранние интеграции, в контракте больше не отдаётся. Переключите сценарии на states.utmEnrollParams или access.meta.utmParams.

Пример: PaymentCompleted

Тело ниже — реальный пример тестовой отправки (синтетические значения, точный состав полей):

{
  "event": "PaymentCompleted",
  "timestamp": "2026-07-02T11:16:25.172Z",
  "idempotencyKey": "g9lFWzmF-4BkJaxvFvIEX",
  "data": {
    "payment": {
      "id": 13001,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "archivedAt": null,
      "uuid": "samplePaymentUuid",
      "type": "OneTime",
      "status": "Completed",
      "checkoutPaymentId": "sampleCheckoutPaymentId",
      "checkoutUrl": null,
      "released": true,
      "paidAt": "2026-01-01T00:00:00.000Z",
      "expireAt": null,
      "isCompleted": true,
      "isCanceled": false,
      "meta": {},
      "webhookLogs": [],
      "chargeLogs": [],
      "statusHistoryLogs": [],
      "invoice": {
        "id": 12001,
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z",
        "archivedAt": null,
        "uuid": "sampleInvoiceUuid",
        "humanId": 1001,
        "type": "Regular",
        "status": "Active",
        "totalAmount": 100,
        "discountAmount": 0,
        "currency": "Usd",
        "expireAt": null,
        "isActive": true,
        "user": {
          "id": 1001,
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": "2026-01-01T00:00:00.000Z",
          "archivedAt": null,
          "uuid": "sampleUserUuid",
          "status": "Active",
          "active": true,
          "activated": true,
          "banned": false,
          "alive": true,
          "domain": "id1001",
          "email": "[email protected]",
          "phone": null,
          "tgId": null,
          "vkId": null,
          "appleId": null,
          "extId": null,
          "schoolId": 1,
          "language": "En",
          "timezone": 0,
          "lastOnlineAt": "2026-01-01T00:00:00.000Z",
          "starsBalance": 0,
          "currentTime": "2026-01-01T00:00:00.000Z",
          "isSleepingNow": false,
          "profile": {
            "id": 1001,
            "createdAt": "2026-01-01T00:00:00.000Z",
            "updatedAt": "2026-01-01T00:00:00.000Z",
            "archivedAt": null,
            "userId": 1001,
            "official": false,
            "firstName": "John",
            "lastName": "Doe",
            "fullName": "John Doe",
            "fullNameShort": "John D.",
            "bdate": null,
            "sex": "Ufo",
            "country": null,
            "city": null,
            "role": "Student",
            "status": null,
            "title": null,
            "emojiTitle": null,
            "avatar": {
              "id": 1001,
              "small": "https://storage.example.exode.biz/production/user/1001/sampleAvatar/small/avatar.png",
              "medium": "https://storage.example.exode.biz/production/user/1001/sampleAvatar/medium/avatar.png",
              "maximum": "https://storage.example.exode.biz/production/user/1001/sampleAvatar/avatar.png"
            },
            "titleState": {
              "manualTitle": null,
              "manualEmojiTitle": null,
              "manualNextTitle": null,
              "manualNextEmojiTitle": null,
              "manualExpiredAt": null,
              "locationTitle": null,
              "locationEmojiTitle": null,
              "achievementTitle": null,
              "achievementEmojiTitle": null
            }
          },
          "school": {
            "id": 1,
            "createdAt": "2026-01-01T00:00:00.000Z",
            "updatedAt": "2026-01-01T00:00:00.000Z",
            "archivedAt": null,
            "segment": "Commerce",
            "baseDomain": "school",
            "customDomain": null,
            "accessType": "Public",
            "domainType": "Base",
            "name": "Sample School",
            "description": null,
            "iconUrl": null,
            "active": true,
            "domain": "school",
            "fqdn": "example.exode.biz",
            "publicUrl": "https://example.exode.biz",
            "baseFqdn": "example.exode.biz",
            "isPublic": true,
            "isPrivate": false
          }
        },
        "products": [
          {
            "id": 11001,
            "createdAt": "2026-01-01T00:00:00.000Z",
            "updatedAt": "2026-01-01T00:00:00.000Z",
            "archivedAt": null,
            "originalPrice": 100,
            "totalPrice": 100,
            "discountAmount": 0,
            "discount": null,
            "price": {
              "id": 10001,
              "createdAt": "2026-01-01T00:00:00.000Z",
              "updatedAt": "2026-01-01T00:00:00.000Z",
              "archivedAt": null,
              "mode": "SelfDefinition",
              "type": "OneTime",
              "title": "Sample Price",
              "description": null,
              "amount": 100,
              "previousAmount": null,
              "accessDays": null,
              "infinityAccess": true,
              "active": true,
              "hidden": false,
              "activeFrom": null,
              "activeTo": null,
              "installmentConfig": null,
              "subscriptionConfig": null,
              "isDemo": false,
              "isRecurrent": false,
              "isInstallment": false,
              "isSubscription": false,
              "meta": {}
            },
            "product": {
              "id": 7001,
              "createdAt": "2026-01-01T00:00:00.000Z",
              "updatedAt": "2026-01-01T00:00:00.000Z",
              "archivedAt": null,
              "sellerId": 1,
              "type": "Course",
              "status": "Published",
              "showInCatalog": true,
              "currency": "Usd",
              "publishedAt": "2026-01-01T00:00:00.000Z",
              "saleStartAt": null,
              "saleFinishAt": null,
              "isFree": false,
              "isPublished": true,
              "approves": [],
              "domains": [],
              "course": {
                "id": 2001,
                "createdAt": "2026-01-01T00:00:00.000Z",
                "updatedAt": "2026-01-01T00:00:00.000Z",
                "archivedAt": null,
                "type": "VideoCourse",
                "name": "Sample Course",
                "description": "Sample course description",
                "alias": null,
                "promoVideo": null,
                "order": 0,
                "isBundle": false,
                "tags": [
                  "sample"
                ],
                "seoTags": [],
                "image": {
                  "main": ""
                },
                "settings": {}
              }
            }
          }
        ]
      },
      "acquiring": {
        "id": 1,
        "active": true,
        "uuid": "sampleAcquiringUuid",
        "name": "Sample Acquiring",
        "description": null,
        "hasProviderCommission": false,
        "provider": {
          "id": 1,
          "type": "Card",
          "active": true
        }
      }
    }
  }
}

Диагностика

Повторные попытки

Каждая попытка использует одну и ту же нагрузку и idempotencyKey. Задержки отсчитываются от предыдущей неудачной попытки (≈ 11 / 33 / 77 / 165 минут). Верните успешный код, чтобы остановить повторы.

Временное отключение

Установите active = false, чтобы приостановить доставку без потери конфигурации и секретного ключа. Повторы событий, которые встали в очередь до выключения, прекращаются после ближайшей неудачной попытки.

Логирование

Логируйте event, timestamp, idempotencyKey и результат проверки подписи — это ускорит сверку с нашей стороной при разборе инцидентов.

Обновлено: 2026-09-28 05:04 UTC

Работа с API

Пользователи

Сотрудники (HR)

Группы

Курсы

Доступы и продажи

Отчеты и выгрузки

Кастомные поля

Формы

Нет нужного метода?

Все объекты

Как это работает

Формат сообщения

Проверка подписи

Доставка и повторные попытки

Управление эндпоинтами

Тестовая отправка

Поддерживаемые события

UTM-атрибуция

Пример: PaymentCompleted

Диагностика

​Как это работает

​Формат сообщения

​Проверка подписи

​Доставка и повторные попытки

​Управление эндпоинтами

​Тестовая отправка

​Поддерживаемые события

​UTM-атрибуция

​Пример: PaymentCompleted

​Диагностика

Как это работает

Формат сообщения

Проверка подписи

Доставка и повторные попытки

Управление эндпоинтами

Тестовая отправка

Поддерживаемые события

UTM-атрибуция

Пример: PaymentCompleted

Диагностика