Supported Platform Capabilities

• Inbound: External systems POST to callback_path → converted to OneBot12 events (json/text segments are transparently passed through)
• Outbound: Module Send → POST to outgoing_url (dual bridging)
• API: Bridging identity information and runtime status (minimal set)

v5 Paradigm Update (4.2.0)

• Minimal API DSL: get_self_info, get_status, get_version, get_supported_actions
• Framework Soft Dependency: Runtime detection of ErisPulse>=2.7.1 with prompt; version log output on startup
• Import path updated to Core.Bases

Platform Feature Description — Webhook Universal Bridge Adapter

This document provides a detailed explanation of the bidirectional bridge protocol, field mapping, and implementation features of the Webhook adapter.

Overview

The Webhook Adapter is a protocol-level bridge, not tied to any specific platform. It exchanges messages via HTTP, enabling any system capable of initiating HTTP requests to integrate with ErisPulse.

Inbound Direction                          Outbound Direction
────────────────                          ────────────────
External System                            ErisPulse Module
   │                                         │
   │ POST JSON                               │ Send.Text(...)
   ▼                                         ▼
┌──────────────────────────────────────────────────────┐
│                WebhookAdapter                          │
│  ┌──────────────────┐    ┌──────────────────┐     │
│  │ Inbound Routes    │    │ Outbound Forward │     │
│  │ GET  (Health Check)│    │ client.post()    │     │
│  │ POST (Receive Event)│   │ → outgoing_url   │     │
│  └────────┬─────────┘    └────────▲─────────┘     │
│           │                      │                 │
│           ▼                      │                 │
│  ┌──────────────────┐    ┌──────────────────┐     │
│  │ WebhookConverter │    │ Send Class       │     │
│  │ JSON → OneBot12  │    │ Message Segment → JSON │
│  └────────┬─────────┘    └────────▲─────────┘     │
└───────────┼──────────────────────┼─────────────────┘
            ▼                      │
     adapter.emit(event)    call_api("send_message")
            │                      │
            ▼                      │
       ErisPulse Event System ◄────────┘

Multi-Account Model

Each account is an independent bridge configuration, isolated from each other:

Each account registers routes independently and emits connect independently upon startup.

Inbound Protocols

1. Health Check (GET)

• Path: {callback_path}
• Method: GET
• Authentication: None
• Response:

{"status": "ok", "account": "default"}

2. Receive Event (POST)

• Path: {callback_path}
• Method: POST
• Content-Type: application/json
• Authentication (when secret is configured): Header X-Webhook-Secret or Query ?secret=

Request Body

{
  "user_id": "u123",
  "user_nickname": "用户名",
  "group_id": "群组ID（仅群组会话）",
  "detail_type": "private",
  "message": [
    {"type": "text", "data": {"text": "消息内容"}}
  ],
  "raw": {}
}

Response

{"status": "ok"}

Error responses include HTTP status codes:

3. Field Mapping (Inbound JSON → OneBot12 Event)

Outbound Protocols

1. Sending Messages

When the module calls methods such as Send.To(...).Text(...), the adapter sends a POST request to outgoing_url:

• Method: POST
• Content-Type: application/json
• Authentication Header (when secret is configured): X-Webhook-Secret: {secret}

Request Body

{
  "target_type": "private",
  "target_id": "target_user_id",
  "account": "default",
  "message": [
    {"type": "text", "data": {"text": "Message content"}}
  ],
  "timestamp": 1700000000
}

2. Response Standardization

The adapter standardizes the response from the outbound target into the ErisPulse standard response format:

{
  "status": "ok",
  "retcode": 0,
  "data": {"message_id": "...", ...},
  "message_id": "...",
  "message": "",
  "webhook_raw": {}
}

The message ID is extracted from the message_id field of the target's response JSON. If the target does not return a message_id, it will be an empty string.

If the request fails, an error response is returned (with status: "failed", retcode: 33001).

Send Method

At / AtAll / Reply decorators are provided by the framework base class and merged into message segments via _apply_modifiers.

Event Extension Methods (WebhookEventMixin)

Feature Matrix

Notes

1. One-way Outbound: If outgoing_url is left empty, the account will only receive inbound messages, and sending operations will return an error.
2. Secret Security: secret is stored as an encrypted value in the configuration (metadata secret), and HTTPS is recommended for transmission.
3. Unique Path: The callback_path for multiple accounts must be unique to avoid routing conflicts.
4. Idempotency: The adapter does not guarantee deduplication of inbound events; external systems should handle retries themselves.
5. Timeout: Outbound requests use ErisPulse's built-in client and inherit the global timeout configuration.