Webhooks Engine & Event Notifications

RUSEON Core features an asynchronous Webhooks Engine (internal/events/webhooks.go) that dispatches real-time HTTP POST notifications to external services, messaging bots, and SIEM security platforms when operational events occur.

---

1. Supported Event Types

Event Name	Trigger Condition	Payload Data
camera.online	Camera successfully connected and streaming	camera_id, name, fps, resolution, timestamp
camera.offline	Camera stream disconnected / RTSP timeout	camera_id, last_error, reconnect_count, timestamp
recording.segment_closed	fMP4 hourly segment closed and cataloged	camera_id, file_path, duration_sec, size_bytes
retention.pruned	Storage cleaner deleted expired recordings	camera_id, deleted_files_count, freed_bytes
ai.detection	Neural network triggered event rule	camera_id, class_name, confidence, bounding_box

---

2. Payload Structure & HMAC-SHA256 Signature

Every webhook request includes standard security and tracing headers:

• Content-Type: application/json
• X-Ruseon-Event: camera.offline
• X-Ruseon-Delivery: d8f3a9e1-5b2c-4e89-a1b7-99c0e4811a2f
• X-Ruseon-Signature: sha256=2c5c... (HMAC-SHA256 hex digest computed using webhook.secret)

Sample Webhook JSON Body:

{
  "event": "camera.offline",
  "delivery_id": "d8f3a9e1-5b2c-4e89-a1b7-99c0e4811a2f",
  "timestamp": 1786802400,
  "data": {
    "camera_id": "cam_entrance_01",
    "name": "Front Entrance Gate",
    "last_error": "RTSP connection reset by peer",
    "reconnect_count": 3
  }
}

---

3. Webhook Receiver Verification Example (Node.js)

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.raw({ type: 'application/json' }));

const WEBHOOK_SECRET = 'your_configured_webhook_secret';

app.post('/api/ruseon-webhook', (req, res) => {
  const signature = req.headers['x-ruseon-signature'];
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  const digest = 'sha256=' + hmac.update(req.body).digest('hex');

  if (signature !== digest) {
    return res.status(401).send('Invalid HMAC signature');
  }

  const payload = JSON.parse(req.body.toString());
  console.log(`Received event ${payload.event} for camera ${payload.data.camera_id}`);
  res.status(200).send('OK');
});

app.listen(3000);

---

4. Configuration Reference

webhooks:
  enabled: true
  endpoints:
    - url: "https://api.company.com/v1/ruseon-events"
      secret: "your_configured_webhook_secret"
      events:
        - "camera.online"
        - "camera.offline"
        - "ai.detection"
      timeout: "5s"
      max_retries: 3
      circuit_breaker:
        failure_threshold: 5
        cooldown_period: "60s"

Related Documentation

• Integrations Overview
• MQTT Integration
• Event Bus Architecture
• Events Configuration Reference