Документация по возможностям платформы универсального мостового адаптера Webhook
WebhookAdapter — это двунаправленный мостовой адаптер уровня протокола, не привязанный к какой-либо конкретной платформе: на входе он преобразует JSON, отправляемый внешними системами методом POST, в события OneBot12, а на выходе преобразует вызовы Send модулей в POST-запросы к внешним системам.
Информация о документе
- Версия соответствующего модуля: 4.3.2
- Сопровождающий: ErisPulse
- Последнее обновление: 2026-11-10
Основная информация
- Краткое описание платформы: любая система, способная отправлять HTTP-запросы, может подключиться к ErisPulse через данный адаптер
- Название адаптера: WebhookAdapter
- Идентификатор платформы:
webhook - Поддержка мультиаккаунта: каждый аккаунт — независимая конфигурация моста (bot_id / callback_path / outgoing_url / secret)
- Требование к фреймворку: мягкая зависимость
ErisPulse>=2.7.1(проверка и уведомление во время выполнения, не обязательна)
Возможности подключённой платформы
- Входящие: внешняя система отправляет POST на callback_path → преобразуется в событие OneBot12 (сегменты json/text передаются прозрачно)
- Исходящие: вызов Send модуля → POST на outgoing_url (двойной мост)
- API: информация об идентификации моста и состоянии работы (минимальный набор)
Обновление парадигмы v5 (4.2.0)
- Минимальный набор Api DSL: get_self_info/get_status/get_version/get_supported_actions
- Мягкая зависимость от фреймворка: проверка ErisPulse>=2.7.1 во время выполнения с уведомлением; вывод журнала версии при запуске
- Пути импорта обновлены до Core.Bases
Соответствие стандартам (4.3.2)
Структура ответов и коды ошибок соответствуют спецификации ответов API.
Поля событий
- Дозаполнение поля
message_idверхнего уровня в событиях сообщений: приоритетно прозрачно передаётсяmessage_idиз входящего body, при отсутствии подставляется uuid (чтобы избежать пустых значений при дедупликации/ответе по message_id на нижестоящих уровнях) - Инъекция
self.account_idв событие (имя аккаунта): в сценариях с несколькими аккаунтамиevent.reply()автоматически маршрутизируется к аккаунту, принявшему данное событие - Подстановка пустой строки для
alt_message: если во входящих данных не указано, добавляется пустая строка, гарантируя полноту стандартных полей - Имя сегмента JSON изменено на
webhook_json: «голые» сегментыjsonбез платформенного префикса нормализуются вwebhook_json(в соответствии с правилами именования расширенных сегментов платформы) - Converter повторно использует фреймворковый
BaseConverter(общие поля строятся унифицированно черезbuild_base_event) get_self_infoдополняется стандартными полями:user_id(bot_id аккаунта) /user_name/user_displayname(webhook:{имя аккаунта})
Спецификация кодов ошибок
| retcode | Значение | Описание |
|---|---|---|
| 0 | Успех | — |
| 33001 | Сетевая ошибка | Сбой исходящего POST к целевой системе (соединение/тайм-аут и т.п.) |
| 10003 | Ошибка параметров | Не настроен исходящий URL, отсутствуют параметры и т.п. |
Аккаунты и мультиаккаунт
call_apiподдерживает два совместимых поля аккаунта:account_id(стандартное имя) /_account_id(старое имя); ApiDSL фреймворка (Api.Using(...)) адаптирует их автоматическиSendчитаетsend_context(с откатом к аккаунту события): при вызовеSendиз контекста события по умолчанию используется аккаунт-источник
Обзор
Адаптер Webhook — это мост уровня протокола, не привязанный к какой-либо конкретной платформе. Он отправляет и принимает сообщения по HTTP, благодаря чему любая система, способная отправлять HTTP-запросы, может подключиться к ErisPulse.
Входящее направление Исходящее направление
────────────────────── ──────────────────────
Внешняя система Модуль ErisPulse
│ │
│ POST JSON │ Send.Text(...)
▼ ▼
┌───────────────────────────────────────────────────────────┐
│ WebhookAdapter │
│ ┌──────────────────────────────────┐ ┌─────────────────────┐ │
│ │ Входящие маршруты │ │ Исходящая пересылка │ │
│ │ GET (проверка работоспособности) │ │ client.post() │ │
│ │ POST (приём событий) │ │ → outgoing_url │ │
│ └─────────────┬────────────────────┘ └────────▲────────────┘ │
│ │ │ │
│ ▼ │ │
│ ┌──────────────────────────────────┐ ┌─────────────────────┐ │
│ │ WebhookConverter │ │ Класс Send │ │
│ │ JSON → OneBot12 │ │ Сегменты → JSON │ │
│ └─────────────┬────────────────────┘ └────────▲────────────┘ │
└────────────────┼──────────────────────────────────┼───────────────┘
▼ │
adapter.emit(event) call_api("send_message")
│ │
▼ │
Система событий ErisPulse ◄─────────────────┘
Модель мультиаккаунта
Каждый аккаунт — это независимая конфигурация моста, не зависящая от других:
| Аккаунт | bot_id | callback_path | outgoing_url | secret |
|---|---|---|---|---|
default |
webhook_bot |
/webhook/default |
https://a.com/recv |
key1 |
discord |
discord_bot |
/webhook/discord |
https://b.com/send |
key2 |
Каждый аккаунт при запуске независимо регистрирует маршруты и независимо выполняет emit connect.
Поля конфигурации аккаунта
| Поле | Обязательно | Описание |
|---|---|---|
bot_id |
Нет | Идентификатор бота (которого представляет данный мост) |
callback_path |
Нет | Путь входящего обратного вызова (поддерживается плейсхолдер {account}) |
outgoing_url |
Нет | Целевой URL исходящих запросов (при отправке сообщений модулем на этот адрес выполняется POST) |
secret |
Нет | Ключ аутентификации (если оставить пустым — проверка отключается; в панели конфигурации хранится в зашифрованном виде) |
Входящий протокол
1. Проверка работоспособности (GET)
- Путь:
{callback_path} - Метод:
GET - Аутентификация: отсутствует
- Ответ:
{"status": "ok", "account": "default"}
2. Приём событий (POST)
- Путь:
{callback_path} - Метод:
POST - Content-Type:
application/json - Аутентификация (если настроен secret): Header
X-Webhook-Secretили Query?secret=
Тело запроса (Body)
{
"user_id": "u123",
"user_nickname": "Имя пользователя",
"group_id": "ID группы (только для групповых сессий)",
"detail_type": "private",
"message_id": "необязательно, прозрачно передаётся как message_id события (при отсутствии автоматически генерируется uuid)",
"alt_message": "необязательно, текстовый резерв",
"message": [
{"type": "text", "data": {"text": "Содержимое сообщения"}}
],
"raw": {}
}
| Поле | Обязательно | Описание |
|---|---|---|
user_id |
Да | ID отправителя |
user_nickname |
Нет | Ник отправителя |
group_id |
Нет | ID группы/канала (указывается для групповых сессий) |
detail_type |
Нет | Тип сессии (private/group); если не задан, используется значение аккаунта по умолчанию |
message_id |
Нет | ID сообщения, прозрачно передаётся в поле верхнего уровня message_id события (при отсутствии подставляется uuid) |
alt_message |
Нет | Текстовый резерв; при отсутствии подставляется пустая строка |
message |
Да | Массив сегментов сообщений OneBot12 |
raw |
Нет | Исходные данные, сохраняются без изменений в webhook_raw |
Ответ
{"status": "ok"}
Ответы с ошибками сопровождаются HTTP-кодами состояния:
| Код состояния | Значение |
|---|---|
| 400 | Некорректный JSON / body не является объектом |
| 401 | Ошибка аутентификации |
| 404 | Неизвестный аккаунт |
| 500 | Сбой диспетчеризации события |
3. Сопоставление полей (входящий JSON → событие OneBot12)
| Входящий JSON | Поле события OneBot12 | Описание |
|---|---|---|
| — | id |
Генерируется автоматически |
| — | time |
Текущая метка времени Unix (в секундах) |
| — | type |
Фиксированное значение message |
detail_type |
detail_type |
Если не задан, используется значение аккаунта по умолчанию |
| — | platform |
Фиксированное значение webhook |
| — | self.platform |
Фиксированное значение webhook |
| — | self.user_id |
bot_id аккаунта |
| — | self.account_id |
Имя аккаунта (инъекция с 4.3.2, маршрутизация при мультиаккаунте) |
user_id |
user_id |
Прозрачная передача |
user_nickname |
user_nickname |
Прозрачная передача (опционально) |
group_id |
group_id |
Прозрачная передача (опционально) |
message_id |
message_id |
Прозрачная передача, при отсутствии подставляется uuid (4.3.2) |
alt_message |
alt_message |
Прозрачная передача, при отсутствии подставляется пустая строка (4.3.2) |
message |
message |
Прозрачная передача |
| Полное body | webhook_raw |
Исходный запрос |
| Имя аккаунта | webhook_account |
Имя аккаунта, породившего событие |
type или message |
webhook_raw_type |
Тип исходного события |
«Голый» сегмент
json({"type": "json", ...}) на обеих сторонах — входящей и исходящей — нормализуется в сегментwebhook_json.
Исходящий протокол
1. Отправка сообщений
Когда модуль вызывает методы вида Send.To(...).Text(...), адаптер отправляет POST-запрос на outgoing_url:
- Метод:
POST - Content-Type:
application/json - Header аутентификации (если настроен secret):
X-Webhook-Secret: {secret}
Тело запроса (Body)
{
"target_type": "private",
"target_id": "target_user_id",
"account": "default",
"message": [
{"type": "text", "data": {"text": "Содержимое сообщения"}}
],
"timestamp": 1700000000
}
| Поле | Описание |
|---|---|
target_type |
Тип цели (из Send.To(type, id)); если не задан, используется значение аккаунта по умолчанию |
target_id |
ID цели (из Send.To) |
account |
Имя аккаунта, выполняющего отправку |
message |
Массив сегментов сообщений OneBot12 |
timestamp |
Метка времени отправки (в секундах) |
2. Стандартизация ответа
Адаптер нормализует ответ, возвращённый исходящей целью, к стандартному формату ответов ErisPulse:
{
"status": "ok",
"retcode": 0,
"data": {"message_id": "...", ...},
"message_id": "...",
"message": "",
"webhook_raw": {}
}
ID сообщения извлекается из поля message_id в JSON-ответе цели. Если цель не вернула message_id, используется пустая строка.
При сбое запроса возвращается ответ с ошибкой (status: "failed", retcode: 33001).
Методы Send
| Метод | Описание |
|---|---|
Text(text) |
Отправка текста, упаковывается в [{"type":"text","data":{"text":text}}] |
Image(file) |
Отправка изображения, упаковывается в [{"type":"image","data":{"file":file}}] |
Raw_ob12(message) |
Отправка исходных сегментов сообщений OneBot12 |
Json(data) |
Прозрачная передача исходного JSON, упаковывается в [{"type":"webhook_json","data":{"raw":data}}] |
Модификаторы At / AtAll / Reply предоставляются базовым классом фреймворка и объединяются в сегменты сообщений через _apply_modifiers.
Методы расширения событий (WebhookEventMixin)
| Метод | Описание |
|---|---|
get_raw_data() |
Получение исходного тела запроса (webhook_raw) |
get_detail_type() |
Получение типа сессии |
get_webhook_account() |
Получение имени аккаунта, породившего данное событие |
Матрица возможностей
| Возможность | Поддержка |
|---|---|
| Мультиаккаунт | ✅ Независимый мост для каждого аккаунта |
| Входящая аутентификация | ✅ Два режима: Header / Query |
| Проверка работоспособности | ✅ GET возвращает состояние |
| Исходящая аутентификация | ✅ Header содержит secret |
| Стандартные события OneBot12 | ✅ Полный набор стандартных полей |
| Meta-события | ✅ connect / disconnect |
| Обнаружение маршрутов | ✅ Регистрация в пространстве имён webhook |
| WebSocket | ❌ Только HTTP |
| Загрузка медиафайлов | ❌ Прозрачная передача по URL, бинарные данные не пересылаются |
Важные замечания
- Однонаправленный исходящий канал: если
outgoing_urlоставлен пустым, аккаунт работает только на приём входящих; операции отправки возвращают ошибку (retcode: 10003) - Безопасность ключа:
secretхранится в конфигурации в зашифрованном виде (metadata secret); для передачи рекомендуется использовать HTTPS - Уникальность путей:
callback_pathразных аккаунтов не должны совпадать, чтобы избежать конфликтов маршрутов - Идемпотентность: адаптер не гарантирует дедупликацию входящих событий; внешняя система должна самостоятельно обрабатывать повторные попытки
- Тайм-аут: исходящие запросы используют встроенный
clientErisPulse и наследуют глобальную конфигурацию тайм-аута