> For the complete documentation index, see [llms.txt](https://developer.perculus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.perculus.com/v2-tr/diger/webhooklar.md).

# Webhooklar

## **Giriş** 

Groups, 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, Groups 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)**

```json
{ 
    "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)

```json
{
    "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)

```json
{ 
    "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.constructor.tech/files/0f19be98e5442ec8f9439c7435f5a7f.mp4?token=xhiUZSLoFe4y9VLCYz17TZiKcZk%3D" 
} 
```

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

```json
{
    "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ı 

```json
{ 
    "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

<table><thead><tr><th width="130">Parametre</th><th width="436">Açıklama</th><th>Tip</th></tr></thead><tbody><tr><td><strong>request_id</strong></td><td>Bu benzersiz tanımlayıcı mesajı tanımlar. Mesajları takip etmek ve sorunları gidermek için kullanılabilir.</td><td>Hepsi</td></tr><tr><td><strong>type</strong></td><td>Mesaj tipi</td><td>Hepsi</td></tr><tr><td><strong>session_id</strong></td><td>Oturum IDsi</td><td>Hepsi</td></tr><tr><td><strong>token</strong></td><td>Bu, webhook uç noktası tarafından Groups platformunu doğrulamak için kullanılan kimlik doğrulama belirtecidir. "<a href="#token-olusturma-ve-dogrulama">Token oluşturma ve doğrulama</a>" bölümüne bakınız.</td><td>Hepsi</td></tr><tr><td><strong>status</strong></td><td>SessionReportEvent ve SingleVideoEvent mesajları için bu alan <em>hazır</em> ve <em>başarısız</em> olmak üzere iki değer alabilir. SessionReportEvent yükündeki <em>status</em> alanı, oturumun doğru şekilde paketlenip paketlenmediğini gösterir. Benzer şekilde, SingleVideoEvent yükündeki <em>status</em> alanı, oturum videosunun başarıyla oluşturulup oluşturulmadığını gösterir. Eğer durum <em>başarısız</em> ise, hata öğesi içinde bir hata mesajı iletilir. SessionStatusEvent için <em>başladı</em> veya <em>bitti</em> değerlerini alabilir.</td><td>Hepsi</td></tr><tr><td><strong>video_url</strong></td><td>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.</td><td>SingleVideoEvent</td></tr><tr><td><strong>date</strong></td><td>Bu öğe, durum alanının değerine bağlı olarak oturumun ne zaman başladığını veya bittiğini belirtir.</td><td>SessionStatusEvent</td></tr><tr><td><strong>error</strong></td><td>Bu öğe, herhangi bir hata durumunda olayın hata metnini içerir. Hata olmadığında atlanabilen isteğe bağlı bir öğedir.</td><td>SessionReportEvent &#x26;<br>SingleVideoEvent</td></tr></tbody></table>

## Token oluşturma ve doğrulama

Alıcı sistem, mesajlar içinde gönderilen kimlik doğrulama belirtecini doğrulayarak Groups sistemini doğrulayabilir. Yukarıdaki bölümlerde gösterildiği gibi, Groups 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 Groups ve alıcı taraf tarafından bilinen özel bir bilgi parçasıdır.

**Örnek oluşturma kodu:**

```csharp
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

```csharp
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; 
} 
```