🪝Webhooklar

Giriş

Perculus, belirli olaylar hakkında dış sistemleri bilgilendirmek için web kancalarını (webhook) kullanır. Bu işlevselliği kullanmak için, webhook uç noktası URL'si (dinleyici URL'si olarak da bilinir) ve olay türü dahil olmak üzere bilgileri depolamak için bir webhook kaydedilmelidir. Bir webhook ile ilişkili bir olay gerçekleştiğinde, ilgili URL'ye bir HTTP POST yükü gönderilir. Bu özelliği kullanmak ve webhook URL'nizi kaydetmek istiyorsanız lütfen destek ekibiyle iletişime geçin.

Olaylar ve Mesajlar

Aşağıda, Perculus olaylarının ve ilgili webhook'ları bilgilendirmek için kullanılan mesajların listesi bulunmaktadır.

SessionReportEvent

Bu olay, bir oturum paketlendikten ve rapor verileri kullanılabilir olduktan sonra gönderilir. Durum hazır veya başarısız olabilir. Raporun hazırlanması sırasında bir hata oluştuysa, mesaja bir hata metni de dahil edilir.

SessionReportEvent Mesajı (Başarılı İşlem)

{ 
    "request_id": "bd943129-f2eb-4b52-9bf9-784c87d1b80e",
    "type": "SessionReportEvent",
    "session_id": "805368AF-B096-42D4-8233-1B0C0EBF1DB2",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",
    "status": "ready"     
} 

SessionReportEvent Mesaji (Başarısız İşlem)

{
    "request_id": "bd943129-f2eb-4b52-9bf9-784c87d1b80e",
    "type": "SessionReportEvent",
    "session_id": "805368AF-B096-42D4-8233-1B0C0EBF1DB2",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",     
    "status": "failed",
    "error": "error text comes here" 
} 

SingleVideoEvent

Bu olay, video dosyası indirilmeye hazır olduğunda gönderilir. Eğer durum başarısız ise, mesaja bir hata metni de dahil edilir.

SingleVideoEvent Mesajı (Başarılı İşlem)

{ 
    "request_id": "0489b550-df7f-4807-a693-22fcd6c9ccf5", 
    "type": "SingleVideoEvent",
    "session_id": "AF7F81CA-167B-43C0-94F7-E6835B30B043",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",
    "status": "ready",
    "video_url": "https://storage-system.perculus.com/files/0f19be98e5442ec8f9439c7435f5a7f.mp4?token=xhiUZSLoFe4y9VLCYz17TZiKcZk%3D" 
} 

SingleVideoEvent Mesajı (Başarısız İşlem)

{
    "request_id": "bd943129-f2eb-4b52-9bf9-784c87d1b80e",
    "type": "SingleVideoEvent",
    "session_id": "AF7F81CA-167B-43C0-94F7-E6835B30B043",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",
    "status": "failed",
    "error": "error text comes here" 
} 

SessionStatusEvent

Bu olay, bir oturum başlatıldığında veya bittiğinde gönderilir. Olay verileri bir JSON yükü olarak kapsüllenir ve webhook uç noktası URL'sine bir HTTP POST isteğinde bulunulur.

SessionStatusEvent Mesajı

{ 
    "request_id": "bd943129-f2eb-4b52-9bf9-784c87d1b80e",
    "type": "SessionStatusEvent",
    "session_id": "805368AF-B096-42D4-8233-1B0C0EBF1DB2",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",
    "status": "started",
    "date": "2024-01-23T17:41:07"
} 

Message Fields

Parametre	Açıklama	Tip
request_id	Bu benzersiz tanımlayıcı mesajı tanımlar. Mesajları takip etmek ve sorunları gidermek için kullanılabilir.	Hepsi
type	Mesaj tipi	Hepsi
session_id	Oturum IDsi	Hepsi
token	Bu, webhook uç noktası tarafından Perculus platformunu doğrulamak için kullanılan kimlik doğrulama belirtecidir. "Token oluşturma ve doğrulama" bölümüne bakınız.	Hepsi
status	SessionReportEvent ve SingleVideoEvent mesajları için bu alan hazır ve başarısız olmak üzere iki değer alabilir. SessionReportEvent yükündeki status alanı, oturumun doğru şekilde paketlenip paketlenmediğini gösterir. Benzer şekilde, SingleVideoEvent yükündeki status alanı, oturum videosunun başarıyla oluşturulup oluşturulmadığını gösterir. Eğer durum başarısız ise, hata öğesi içinde bir hata mesajı iletilir. SessionStatusEvent için başladı veya bitti değerlerini alabilir.	Hepsi
video_url	Bu öğe, video içeriğinin bulunduğu URL'yi belirtir. Bu URL, video içeriğine erişmek için kullanılabilir ve 24 saat sonra süresi dolar.	SingleVideoEvent
date	Bu öğe, durum alanının değerine bağlı olarak oturumun ne zaman başladığını veya bittiğini belirtir.	SessionStatusEvent
error	Bu öğe, herhangi bir hata durumunda olayın hata metnini içerir. Hata olmadığında atlanabilen isteğe bağlı bir öğedir.	SessionReportEvent & SingleVideoEvent

Token oluşturma ve doğrulama

Alıcı sistem, mesajlar içinde gönderilen kimlik doğrulama belirtecini doğrulayarak Perculus sistemini doğrulayabilir. Yukarıdaki bölümlerde gösterildiği gibi, Perculus her webhook URL isteği yükünde bir belirteç öğesi içerir. Aşağıdaki formattadır: token = <timestamp>|<hmac>

hmac, karma tabanlı bir mesaj kimlik doğrulama kodudur. Bir gizli anahtar ve zaman damgası kullanılarak oluşturulur.

timestamp, belirteç oluşturma zamanından 1/1/1970 UTC'ye kadar geçen saniye sayısıdır. Unix zamanı olarak da bilinir.

secret, yalnızca Perculus ve alıcı taraf tarafından bilinen özel bir bilgi parçasıdır.

Örnek oluşturma kodu:

var token_content = utf8_bytes(timestamp);
var hmac_sha256_key = utf8_bytes(secret);
var hmac_sha256_generator = hmac_sha256(hmac_sha256_key);
var hmac = hmac_sha256_generator.compute_hash(token_content);
var token = timestamp + "|" + hmac;

Gizli anahtar alıcı taraf tarafından da bilindiğinden, alıcı yukarıdaki algoritmayı kullanarak belirteç içine gömülü zaman damgasını ve gizli anahtarı kullanarak hmac'i yeniden oluşturabilir. Böylece alıcı şunları doğrulayabilir:

• Zaman damgasının en fazla N dakika eski olması durumunda belirtecin süresinin dolup dolmadığını kontrol ederek isteğin geçerliliğini. Burada, N parametresinin belirlenmesi alıcı tarafa bağlıdır.

• İsteğin özgünlüğünü (hmac'lerin eşit olup olmadığını kontrol ederek). Aşağıdaki C# kod parçası, belgede yukarıda açıklandığı gibi bir gizli anahtar ve zaman damgası kullanarak bir kimlik doğrulama belirteci oluşturan bir yöntemdir.

C# İçin Örnek Token Oluşturma

public static string CreateAuthToken(string secret, DateTime httpRequestUTCDate) { 
    if (String.IsNullOrEmpty(secret)) 
        throw new ArgumentException("secret cannot be empty"); 
    // Calculate Unix timestamp which is 
    // the total seconds passed since 1/1/1970 UTC 
    var timestamp = Math.Floor((httpRequestUTCDate - new DateTime(1970, DateTimeKind.Utc)).TotalSeconds).ToString(); 
    // Generate an hmac using HMAC-SHA256 algorithm 
    var keyBytes = System.Text.Encoding.UTF8.GetBytes(secret); 
    var hmacsha256 = new System.Security.Cryptography.HMACSHA256(keyBytes);
    var messageBytes = System.Text.Encoding.UTF8.GetBytes(timestamp);
    var hmac = Convert.ToBase64String(hmacsha256.ComputeHash(messageBytes));
    // Return the token, which combines unix timestamp and hmac 
    return timestamp + "|" + hmac; 
}