RWI Events & Webhooks

RWI (Real-time WebSocket Interface) is RustPBX’s real-time event bus. In addition to WebSocket real-time push, it also supports HTTP Webhooks to forward events to external systems.

1. RWI Architecture

RustPBX internal events
    │
    ▼
RWI Gateway
    │
    ├── WebSocket connection (real-time control)
    │     ws://host:8080/rwi/ws
    │     Sub-protocol: rwi-v1
    │
    └── HTTP Webhook (event forwarding)
          POST https://your-server/webhook

2. Webhook Configuration

In 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"

# Optional: event type filtering (leave empty or omit to forward all)
events = [
  "call_hangup",
  "call_answered",
  "queue_joined",
  "queue_agent_connected",
  "agent_state_changed",
  "dtmf",
  "ivr_step_trace",
  "record_stopped"
]

2.1 Configuration Parameters

3. Webhook Payload Format

Each POST request body:

{
  "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. Deduplication

Webhooks have built-in deduplication:

• Ring buffer of 4096 (call_id, sequence) records
• Events with the same (call_id, sequence) are not sent twice
• Handles scenarios where the same event is forwarded from multiple call owners

5. Complete Event Type List

5.1 Call Lifecycle

5.2 Media

5.3 Recording

5.4 Queue / ACD

5.5 Agents

5.6 Extensions

5.7 IVR

5.8 Conference

5.9 Supervisor

5.10 Parallel Originate

5.11 SIP Signaling

5.12 Session Recovery

6. Webhook Receiver Examples

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 Real-time Connection (Supplement)

In addition to Webhooks, you can also subscribe to events in real-time via 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 Session Recovery

After a WebSocket disconnect and reconnect, sessions can be recovered via the last_sequence parameter:

• Gateway caches the latest 1000 events
• 60-second retention period
• Monotonically increasing sequence numbers

8. Typical Use Cases