راهنمای وب‌هوک
رویدادهای کلاس، در برنامه شما

checksum = HASH("hooks/create" + exactQueryString + apiSecret)

<?php
// Run on your own application server after webhook access is enabled.
$base = rtrim((string) getenv('BBB_API_URL'), '/') . '/';
$secret = (string) getenv('BBB_SHARED_SECRET');
$algorithm = (string) (getenv('BBB_API_HASH') ?: 'sha1');
if (!str_starts_with($base, 'https://') || $secret === ''
    || !in_array($algorithm, ['sha1','sha256','sha384','sha512'], true)) {
    throw new RuntimeException('Configure API URL, secret and hash');
}
$method = 'hooks/create'; // Include "hooks/" in the checksum input.
$params = [
    'callbackURL' => 'https://your-app.example.com/hooks/bbb',
    'meetingID' => 'course-42-session-1',
    'eventID' => 'meeting-created,meeting-ended,user-joined,user-left',
    'getRaw' => 'false',
];
$query = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
$url = $base . $method . '?' . $query . '&checksum='
    . hash($algorithm, $method . $query . $secret);
$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
]);
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($response === false || $status !== 200) throw new RuntimeException('Transport error');
libxml_use_internal_errors(true);
$xml = simplexml_load_string($response, 'SimpleXMLElement', LIBXML_NONET);
if ($xml === false || (string) $xml->returncode !== 'SUCCESS') {
    throw new RuntimeException('Hook registration failed');
}
$hookID = (string) $xml->hookID;
// Save hookID in your application database; do not log the signed URL.

// List hooks for a meeting:
$method = 'hooks/list';
$params = ['meetingID' => 'course-42-session-1'];

// Remove one registered hook (only after explicit app authorization):
$method = 'hooks/destroy';
$params = ['hookID' => $storedHookID];

{
  "data": {
    "type": "event",
    "id": "meeting-ended",
    "attributes": {
      "meeting": {
        "external-meeting-id": "course-42-session-1",
        "internal-meeting-id": "example-internal-id"
      }
    },
    "event": { "ts": 1793700000000 }
  }
}

callbackChecksum = HASH(exactRegisteredCallbackURL + exactRawRequestBody + webhookSecret)

CREATE TABLE webhook_inbox (
  delivery_key TEXT PRIMARY KEY,
  payload TEXT NOT NULL,
  received_at TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending'
);
CREATE INDEX webhook_inbox_status ON webhook_inbox(status, received_at);

<?php
// Educational receiver for getRaw=false + checksum authentication.
// Install in YOUR application, not in the documentation website.
// Requires PHP 8.1+ and PDO SQLite. Initialize inbox using inbox.sql first.
declare(strict_types=1);
header('Cache-Control: no-store');
header('Content-Type: text/plain; charset=utf-8');
function reply(int $status, string $message): never {
    http_response_code($status);
    echo $message;
    exit;
}
if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
    header('Allow: POST');
    reply(405, 'POST required');
}
$type = strtolower(trim(explode(';', $_SERVER['CONTENT_TYPE'] ?? '')[0]));
if ($type !== 'application/x-www-form-urlencoded') reply(415, 'Unsupported media type');

$secret = (string) getenv('BBB_WEBHOOK_SECRET');
$callback = (string) getenv('BBB_WEBHOOK_CALLBACK_URL');
$algorithm = (string) (getenv('BBB_WEBHOOK_HASH') ?: 'sha256');
$private = realpath((string) getenv('BBB_WEBHOOK_PRIVATE_DIR'));
$public = realpath($_SERVER['DOCUMENT_ROOT'] ?? '');
// This example requires a callback URL without a query string or fragment.
if ($secret === '' || !filter_var($callback, FILTER_VALIDATE_URL)
    || parse_url($callback, PHP_URL_SCHEME) !== 'https'
    || parse_url($callback, PHP_URL_QUERY) !== null
    || parse_url($callback, PHP_URL_FRAGMENT) !== null
    || !in_array($algorithm, ['sha1', 'sha256', 'sha384', 'sha512'], true)
    || !$private || !$public || !is_writable($private)
    || $private === $public || str_starts_with($private, $public . DIRECTORY_SEPARATOR)) {
    reply(503, 'Receiver configuration incomplete');
}
// Match the sender's configured algorithm; do not guess it from user input.
$maxBytes = 1048576;
$body = file_get_contents('php://input', false, null, 0, $maxBytes + 1);
if ($body === false || strlen($body) > $maxBytes) reply(413, 'Payload too large');
$provided = $_GET['checksum'] ?? null;
$expected = hash($algorithm, $callback . $body . $secret);
if (!is_string($provided) || !hash_equals($expected, $provided)) {
    reply(403, 'Invalid signature');
}
// Verify the original bytes BEFORE decoding or re-encoding anything.
parse_str($body, $form);
if (!is_string($form['event'] ?? null) || !is_string($form['timestamp'] ?? null)
    || !preg_match('/^[0-9]{13}$/D', $form['timestamp'])) {
    reply(400, 'Invalid envelope');
}
// Example policy: allow retries for 24 hours and 5 minutes of clock skew.
// Adjust to the agreed retry policy; this is not a BBB protocol constant.
$ageMs = (int) floor(microtime(true) * 1000) - (int) $form['timestamp'];
if ($ageMs > 86400000 || $ageMs < -300000) reply(403, 'Timestamp outside accepted window');
try {
    $decoded = json_decode($form['event'], true, 64, JSON_THROW_ON_ERROR);
} catch (JsonException) {
    reply(400, 'Invalid event JSON');
}
if (!is_array($decoded) || $decoded === []) reply(400, 'Empty event');
$events = array_is_list($decoded) ? $decoded : [$decoded];
if (count($events) > 100) reply(413, 'Too many events');
// Server-side allowlist: use your account/course database in production.
$meetings = array_filter(explode(',', (string) getenv('BBB_ALLOWED_MEETING_IDS')));
if (!$meetings) reply(503, 'Configure authorized meetings');
foreach ($events as $event) {
    $data = is_array($event) ? ($event['data'] ?? null) : null;
    $meeting = is_array($data) ? ($data['attributes']['meeting']['external-meeting-id'] ?? null) : null;
    if (!is_array($data) || !is_string($data['id'] ?? null)) reply(400, 'Unsupported event shape');
    if (!is_string($meeting) || !in_array($meeting, $meetings, true)) {
        reply(403, 'Meeting outside receiver scope');
    }
}
// Only accept mapped meeting events in this sample. Recording events may need
// a separate mapping from internal meeting/recording ID to the authorized account.
$dbPath = $private . '/inbox.sqlite';
if (!is_file($dbPath) || is_link($dbPath)) reply(503, 'Initialize inbox first');
try {
    $db = new PDO('sqlite:' . $dbPath, null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
    $db->exec('PRAGMA busy_timeout=1500');
    $key = hash('sha256', $callback . "\n" . $body);
    $db->beginTransaction();
    $stmt = $db->prepare('INSERT INTO webhook_inbox(delivery_key,payload,received_at,status)
        VALUES(?,?,?,?) ON CONFLICT(delivery_key) DO NOTHING');
    $stmt->execute([$key, json_encode($events, JSON_THROW_ON_ERROR), gmdate('c'), 'pending']);
    $db->commit();
} catch (Throwable) {
    if (isset($db) && $db->inTransaction()) $db->rollBack();
    reply(503, 'Inbox temporarily unavailable');
}
// A worker processes pending rows later. Do not send SMS or run slow tasks here.
reply(200, 'Accepted');