Событие
Запись об изменении платежа, игровой сессии, проверки KYC, бонуса, профиля игрока или другого объекта.
Документация / Вебхуки
Вебхуки и доставка событий
Настройте надежную передачу статусов и событий между системами: от формирования сообщения и проверки подписи до подтверждения приема, повторной доставки и контроля ошибок.
События
статусы и изменения
Подпись
проверка подлинности
Повторы
повторная доставка
Контроль
история и диагностика
Путь события
От создания до подтверждения
01
Создать событие
Указать идентификатор, тип, время, объект, статус и связанные данные.
02
Подписать и отправить
Передать событие по HTTPS с подписью и ограниченным временем ожидания.
03
Подтвердить прием
После проверки сохранить событие и быстро вернуть успешный HTTP-ответ.
04
Повторить при ошибке
Повторять доставку с увеличением интервала и сохранять неотправленные события для разбора.
Обзор
Вебхук сообщает об изменении состояния
Отправитель может повторить доставку, поэтому получатель должен проверить источник, подтвердить прием и применить каждое событие только один раз.
Подтверждение
Получатель возвращает успешный HTTP-ответ после проверки и надежного сохранения события.
Восстановление
Повторная отправка и сверка помогают восстановить данные после временной недоступности одной из систем.
Состав события
Какие данные должно содержать событие
Единый состав сообщения упрощает проверку, маршрутизацию, защиту от повторов и поддержку разных типов событий.
Идентификатор события
Уникальное значение, по которому система распознает повторную доставку и находит историю обработки.
Тип события
Понятное стабильное название, которое определяет произошедшее изменение и способ обработки.
Время создания
Дата и время формирования события в согласованном формате и часовом поясе.
Связанный объект
Тип и идентификатор платежа, игрока, раунда, заявки, бонуса или другого объекта.
Версия структуры
Номер версии помогает безопасно изменять состав сообщения без нарушения действующих подключений.
Связь с операцией
Идентификатор исходного запроса, транзакции, сессии или цепочки связанных действий.
Контекст
Бренд, проект, рынок, среда, провайдер и другие данные, необходимые для правильной маршрутизации.
Данные события
Минимальный набор полей для обработки изменения или последующего запроса к API.
Подпись и проверка
Проверка подлинности и целостности события
До изменения данных получатель проверяет защищенное соединение, подпись, время создания и уникальный идентификатор события.
01
Получить исходное сообщение
Проверяйте подпись по исходному содержимому запроса до изменения формата JSON.
02
Проверить время
Отклоняйте запрос, если время события выходит за допустимый интервал.
03
Проверить подпись
Используйте согласованный секрет и алгоритм HMAC или цифровой подписи.
04
Проверить идентификатор
Убедитесь, что событие еще не применялось, и сохраните результат проверки.
Доставка и повторы
HTTP-ответы и повторная доставка
Отправитель должен различать успешный прием, временную ошибку и постоянный отказ, а получатель — отвечать быстро и однозначно.
Успешный HTTP-ответ
Подтверждает, что событие проверено и надежно сохранено для дальнейшей обработки.
Ограниченное ожидание
Не выполняйте длительную обработку до ответа отправителю — сначала сохраните событие.
Повторная отправка
Повторяйте доставку при временной сетевой ошибке, недоступности или отсутствии ответа.
Увеличение интервала
Постепенно увеличивайте паузу между попытками, чтобы не создавать дополнительную нагрузку.
Очередь неотправленных событий
После исчерпания попыток сохраняйте событие для диагностики и ручной обработки.
Ручная повторная отправка
Оператор может повторно отправить выбранное событие без создания новой операции.
Контроль доставки
Отслеживайте количество попыток, ответы, последнюю ошибку и время следующей отправки.
Уведомления
Сообщайте команде о росте ошибок, исчерпании попыток и накоплении событий в очереди.
Обработка событий
Защита от повторов и порядок статусов
Получатель не должен рассчитывать на единственную доставку или строгую последовательность событий.
Однократное применение
Сохранять идентификатор события до изменения данных.
Повторное событие подтверждать без повторного списания, начисления или изменения.
Связывать событие с объектом и его текущим состоянием.
Сохранять событие и бизнес-изменение как единую согласованную операцию.
Порядок и актуальность
Сравнивать время, номер последовательности или версию события.
Не возвращать объект в устаревшее состояние при задержанной доставке.
Разрешать только допустимые переходы между статусами.
При сомнении запрашивать актуальное состояние объекта через API.
Тестирование
Что проверить перед запуском
Проверьте успешную доставку, неверную подпись, повторы, медленный ответ, изменение порядка событий и восстановление после сбоя.
Неверная подпись
Измененное сообщение, неизвестный ключ, просроченное время и неподдерживаемый алгоритм.
Повторная доставка
Одно событие приходит несколько раз до и после завершения обработки.
Медленный ответ
Получатель отвечает слишком долго, соединение разрывается или подтверждение не доходит до отправителя.
Нарушение порядка
Финальный статус приходит раньше промежуточного, а старое событие доставляется после нового.
Недоступный адрес
Проверьте ошибки HTTP 5xx, DNS, TLS, ограничения частоты и полное исчерпание попыток.
История доставки
По идентификатору события должны находиться все попытки, ответы, ошибки и результат ручной отправки.
Чек-лист перед запуском
Рабочая доставка включается после проверки безопасности, защиты от повторов, повторной отправки и контроля ошибок.
Для тестовой и рабочей среды используются разные адреса и секреты подписи.
Подпись проверяется по исходному сообщению с учетом времени создания.
Идентификатор события сохраняется и защищает операции от повторного выполнения.
Получатель быстро возвращает успешный HTTP-ответ после сохранения события.
Настроены повторные попытки, увеличение интервала и ручная отправка.
История доставки и поиск по идентификатору доступны команде поддержки.
Нужно настроить надежную доставку событий?
Передайте список событий, адреса приема и правила изменения статусов. APIACE поможет определить состав сообщений, проверку подписи, повторную доставку и контроль ошибок.