Webhook System

The V.cloud V4 API includes a powerful webhook system with the following features:

Features

• CRUD operations
  Create, read, update, delete webhooks.

• HMAC SHA256 authentication
  Ensures secure webhook delivery.

• Multi-level entity support
  Supports Organization, Project, and Room.

Webhook Authentication

All webhook requests are signed using HMAC SHA256 to ensure authenticity and security.

Signature Generation

The payload is serialized as JSON with sorted keys and encoded using UTF-8.

import hmac, hashlib, json

def generate_signature(secret, payload):
    message = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode()
    return hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()

Signature Verification

• The signature is sent in the X-Vcloud-Signature header of the webhook request.
• Recipients must verify the signature using their secret key to ensure the payload is untampered.

Webhook Payload Structure

Webhook payloads provide detailed information about the event, associated room, project, and organization.

Example Payload

{
  "event": "analytics_proceeded",
  "room": {
    "room_id": "277e1531-a073-4804-a92b-91cc2eb73194"
  },
  "project": {
    "project_id": "0753e658-2753-4d11-8b0e-399714281749",
    "project_name": "try1233"
  },
  "organization": {
    "organization_id": "fa48e943-5311-4d9c-bc3d-6dfaad51b6c3",
    "organization_name": "Try123"
  }
}

Payload Fields

• event — Type of event that triggered the webhook
• room — Contains the room_id where the event occurred
• project — Contains project_id and project_name
• organization — Contains organization_id and organization_name

Available Webhook Events

The following events can trigger webhook notifications.

Room Lifecycle

• room_started — Triggered when a new room is created and started.
• track_published — Triggered with Mic, Share screen and Webcam.
• room_finished — Triggered when a room has completely finished and cleanup is done.
• track_unpublished — When the user turned off Mic, Share screen and Webcam.
• start_rtmp — Triggered when RTMP stream starts.
• end_rtmp — Triggered when RTMP stream stops.

Participant Activity

• participant_joined — Triggered when a participant joins a room.
• participant_left — Triggered when a participant leaves a room.

Session Management

• session_ended — Triggered when a user session ends in a room.

Analytics

• analytics_proceeded — Triggered when analytics data has been processed and is ready.

Recording

• start_recording — Triggered when recording starts.
• recording_proceeded — Triggered when recording is processing or in progress.
• recording_ended — Triggered when recording ends.