RWI 事件与 Webhook

RWI（Real-time WebSocket Interface）是 RustPBX 的实时事件总线。除了 WebSocket 实时推送，还支持 HTTP Webhook 将事件转发到外部系统。

1. RWI 架构

RustPBX 内部事件
    │
    ▼
RWI Gateway
    │
    ├── WebSocket 连接（实时控制）
    │     ws://host:8080/rwi/ws
    │     Sub-protocol: rwi-v1
    │
    └── HTTP Webhook（事件转发）
          POST https://your-server/webhook

2. Webhook 配置

在 config.toml 中：

[rwi_webhook]
url = "https://your-server.example.com/api/rwi/events"
timeout_ms = 5000

[rwi_webhook.headers]
Authorization = "Bearer my-webhook-secret"
X-Source = "rustpbx"

# 可选：事件类型过滤（留空或不设则转发全部）
events = [
  "call_hangup",
  "call_answered",
  "queue_joined",
  "queue_agent_connected",
  "agent_state_changed",
  "dtmf",
  "ivr_step_trace",
  "record_stopped"
]

2.1 配置参数

2.2 投递运行时（0.5+）

Webhook 运行在与 SIP 热路径解耦的专用运行时上:

• 可配置的 worker 线程（rwi_webhook_worker_threads）从有界队列取事件,慢速接收端不会拖垮呼叫处理。
• 失败投递（5xx/429/传输错误）按退避策略重试至多 retries 次;每次尝试携带相同的幂等键和逐字节一致的请求体。
• 每次请求都会记录 URL、状态码和延迟,用于结构化日志,并可选排队延迟指标。
• [rwi_webhook] 段支持热更新——修改 URL、headers 或事件过滤无需重启即可生效。

3. Webhook Payload 格式

每次 POST 请求体：

{
  "rwi": "1.0",
  "sequence": 12345,
  "timestamp": "2026-05-26T10:30:00Z",
  "call_id": "abc123@10.0.0.1",
  "event_type": "call_hangup",
  "event": {
    "call_id": "abc123@10.0.0.1",
    "reason": "normal",
    "duration": 120,
    "sip_code": 200
  }
}

4. 去重机制

Webhook 内置去重：

• 环形缓存 4096 条 (call_id, sequence) 记录
• 相同 (call_id, sequence) 的事件不会重复发送
• 适用于同一事件从多个 call owner 转发的场景

5. 完整事件类型列表

5.1 呼叫生命周期

5.2 媒体

5.3 录音

5.4 队列/ACD

5.5 坐席

5.6 分机

5.7 IVR

5.8 会议

5.9 监控（Supervisor）

5.10 并行外呼

5.11 SIP 信令

5.12 会话恢复

6. Webhook 接收端示例

6.1 Python Flask

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/api/rwi/events", methods=["POST"])
def handle_rwi_event():
    payload = request.json
    event_type = payload.get("event_type")
    call_id = payload.get("call_id")
    event = payload.get("event", {})

    if event_type == "call_hangup":
        print(f"Call {call_id} ended, duration={event.get('duration')}s")
    elif event_type == "queue_agent_connected":
        print(f"Agent {event.get('agent_id')} connected to call {call_id}")
    elif event_type == "agent_state_changed":
        print(f"Agent {event.get('agent_id')} -> {event.get('state')}")

    return jsonify({"status": "ok"})

6.2 Node.js Express

app.post("/api/rwi/events", express.json(), (req, res) => {
  const { event_type, call_id, event, sequence } = req.body;
  console.log(`[${sequence}] ${event_type} on ${call_id}`);
  res.json({ status: "ok" });
});

7. WebSocket 实时连接（补充）

除了 Webhook，也可通过 WebSocket 实时订阅事件：

const ws = new WebSocket("ws://rustpbx:8080/rwi/ws", "rwi-v1");
ws.onmessage = (e) => {
  const data = JSON.parse(e.data);
  console.log(data.event_type, data.call_id);
};

7.1 会话恢复

WebSocket 断连后重连，可通过 last_sequence 参数恢复：

• Gateway 缓存最近 1000 条事件
• 60 秒保留期
• 单调递增 sequence 号

8. 典型应用场景