ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Документация по возможностям платформы универсального мостового адаптера 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, бинарные данные не пересылаются

Важные замечания

  1. Однонаправленный исходящий канал: если outgoing_url оставлен пустым, аккаунт работает только на приём входящих; операции отправки возвращают ошибку (retcode: 10003)
  2. Безопасность ключа: secret хранится в конфигурации в зашифрованном виде (metadata secret); для передачи рекомендуется использовать HTTPS
  3. Уникальность путей: callback_path разных аккаунтов не должны совпадать, чтобы избежать конфликтов маршрутов
  4. Идемпотентность: адаптер не гарантирует дедупликацию входящих событий; внешняя система должна самостоятельно обрабатывать повторные попытки
  5. Тайм-аут: исходящие запросы используют встроенный client ErisPulse и наследуют глобальную конфигурацию тайм-аута