Webhooks – Gerçek Zamanlı Etkinlikler

BigBlueButton Webhooks, toplantı olayları gerçekleştiğinde uygulamanızın gerçek zamanlı HTTP POST bildirimleri almasını sağlar. Sürekli olarak getMeetings veya getMeetingInfo yoklamak yerine, bir callback URL'si kaydedersiniz ve BigBlueButton olayları size otomatik olarak gönderir. Bu bölüm, üç webhook API uç noktasını, callback biçimini, olay türlerini, yeniden deneme davranışını ve sunucu yapılandırmasını kapsar.

Önkoşullar

Webhook uç noktalarının kullanılabilir hâle gelmesi için bbb-webhooks paketinin BigBlueButton sunucusuna önceden kurulmuş olması gerekir:

sudo apt-get install bbb-webhooks

hooks/create — Bir Webhook Kaydet

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/create?<parameters>&checksum=replace-with-checksum

Başarılı Yanıt

<response>
  <returncode>SUCCESS</returncode>
    <hookID>replace-with-hook-id</hookID>
  <permanentHook>false</permanentHook>
  <rawData>false</rawData>
</response>

Yinelenen Kayıt

Aynı callbackURL yeniden kaydedilirse, yanıt yine de SUCCESS döndürür ancak bir duplicateWarning içerir. Mevcut hook değişmeden korunur — meetingID, eventID ve getRaw güncellenmez.

<response>
  <returncode>SUCCESS</returncode>
    <hookID>replace-with-hook-id</hookID>
  <messageKey>duplicateWarning</messageKey>
  <message>There is already a hook for this callback URL.</message>
</response>

Hata Yanıtları

hooks/list — Kayıtlı Webhook'ları Listele

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/list?<parameters>&checksum=replace-with-checksum

Başarılı Yanıt

<response>
  <returncode>SUCCESS</returncode>
  <hooks>
    <hook>
    <hookID>replace-with-hook-id</hookID>
            <callbackURL><![CDATA[https://api-guide.bbbserver.com/callbacks/webhook]]></callbackURL>
    <meetingID><![CDATA[replace-with-meeting-id]]></meetingID>
      <eventID>user-joined,meeting-ended</eventID>
      <permanentHook>false</permanentHook>
      <rawData>false</rawData>
    </hook>
  </hooks>
</response>

Hata Yanıtları

hooks/destroy — Bir Webhook'u Kaldır

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/destroy?<parameters>&checksum=replace-with-checksum

Başarılı Yanıt

<response>
  <returncode>SUCCESS</returncode>
  <removed>true</removed>
</response>

Hata Yanıtları

hooks/ping — Sağlık Kontrolü

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/ping

Bu tanılama uç noktası checksum gerektirmez. Webhook uygulamasına erişilebiliyorsa düz metin olarak bbb-webhooks API up! dizesini döndürür (XML değil, içerik türü text/plain). undocumented

Geri Çağrı Biçimi

Webhook geri çağrıları, içerik türü olacak şekilde HTTP POSTapplication/x-www-form-urlencoded istekleri olarak gönderilir. İstek gövdesi üç alan içerir:

İşlenmiş Callback Gövdesi (getRaw=false)

domain=myserver.com&event=[{"data":{"type":"event","id":"user-joined","attributes":{...},"event":{"ts":1532718316938}}}]&timestamp=1532718316953

Ham Callback Gövdesi (getRaw=true)

domain=myserver.com&event=[{"envelope":{"name":"UserJoinedMeetingEvtMsg","routing":{"sender":"bbb-apps-akka"}},"core":{"header":{...},"body":{...}}}]&timestamp=1532718316953

Geri Çağrı Checksum Doğrulaması

Varsayılan modda, her callback URL'si uygulamanızın doğrulaması gereken bir checksum sorgu parametresi alır:

https://api-guide.bbbserver.com/callbacks/webhook?checksum=replace-with-checksum

Doğrulama formülü şöyledir:

sha<algo>(<callback-URL-without-checksum> + <URL-encoded-body> + <shared-secret>)

Auth 2.0 / Bearer Modu

Alternatif olarak, sunucu auth2_0: true ile yapılandırılabilir. Bu modda callback URL'sine checksum parametresi eklenmez. Bunun yerine paylaşılan gizli anahtar, Bearer başlığında bir Authorization token olarak gönderilir: undocumented

Authorization: Bearer <shared-secret>

Geri Çağrı Davranışı

• Kabul edilen HTTP durum kodları: HTTP 2xx ve HTTP 401 başarılı teslimat olarak kabul edilir. Diğer tüm durum kodları yeniden denemeyi tetikler. undocumented
• Yönlendirmeler: HTTP 3xx yanıtları takip edilir (10 sıçramaya kadar). Yalnızca 10 yönlendirmeden sonra hiçbir 2xx/401'ye ulaşılamazsa callback başarısız sayılır.
• Zaman aşımı: Her geri çağrı isteği için 5 saniyelik bir zaman aşımı vardır (requestTimeout ile yapılandırılabilir).
• Yeniden deneme aralıkları: Başarısızlık durumunda, yeniden denemeler üstel geri çekilme kullanır: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (yaklaşık 5 dakika boyunca 12 deneme, retryIntervals ile yapılandırılabilir).
• Tüm yeniden denemeler tükendiğinde: Kalıcı olmayan hook'lar otomatik olarak kaldırılır. Kalıcı hook'lar ise 60 saniyelik aralıklarla süresiz olarak yeniden denemeye devam eder (permanentIntervalReset ile yapılandırılabilir).

Olay Türleri

Toplantı Olayları

Kullanıcı Olayları

Sohbet ve Notlar Olayları

Anket Olayları

Kayıt ve Oynatma (RAP) Olayları

Sunucu Yapılandırması

Aşağıdaki seçenekler /etc/bigbluebutton/bbb-webhooks.yml veya config/default.yml içinde yapılandırılabilir. Bu seçeneklerin çoğu resmi belgelerde yer almamaktadır. undocumented

Operasyonel Notlar

• Kalıcılık: Hook'lar Redis içinde saklanır ve sunucu yeniden başlatmalarından etkilenmez (başlangıçta yeniden senkronize edilir).
• Sıralama: Geri çağırmalar her hook için sırayla, aynı anda bir tane olacak şekilde gönderilir ve etkinlik sırası korunur.
• URL benzersizliği: Yinelenen tespiti yalnızca callback URL'sine dayanır. Aynı URL, farklı meetingID veya eventID filtreleriyle kaydedilemez — ilk kayıt kazanır.
• Veri temizliği: Dahili toplantı eşlemeleri, bir haftalık hareketsizlikten sonra kaldırılır (mappings.timeout ile yapılandırılabilir, varsayılan: 604800000 ms).
• Sentetik olaylar: Bir toplantı sona erdiğinde, hâlâ bağlı olan tüm kullanıcılar için user-left olayları otomatik olarak üretilir; çünkü BigBlueButton, toplantı bittiğinde kendisi UserLeftMeetingEvtMsg yayınlamaz.
• Özel sohbetler: Yalnızca genel sohbet mesajları chat-group-message-sent etkinlikleri üretir. Özel mesajlar sessizce yok sayılır.