Webhook'lar¶

Bir webhook, kendine ait bir ad ve avatarla tek bir sunucu kanalına mesaj gönderir.

Yönetim yolları bir kullanıcı oturum token'ı veya bir bot token'ı kabul eder. Diğer tüm webhook yolları, kendi yolundaki webhook kimliğini ve gizli token'ı eksiksiz kimlik bilgisi olarak kullanır; bu yollarda Authorization başlığı gerekmez ve hiçbir yetki vermez. Webhook'ları kullanma tipik bir entegrasyonu adım adım anlatır.

Mesaj ve gömme (embed) nesneleri Mesajlar kaynağında tanımlanır.

Yetkilendirme¶

Bir yönetim yolu, sunucu düzeyinde MANAGE_WEBHOOKS iznini ve kanalı olan bir webhook için o kanalda VIEW_CHANNEL ile MANAGE_WEBHOOKS izinlerini gerektirir. Sunucu üyesi olmayan veya bu izinlerden birine sahip olmayan çağıran 403 FORBIDDEN alır. Var olmayan bir kanal veya webhook 404 NOT_FOUND döndürür.

Webhook'lar yalnızca sunucu metin ve ses kanallarında bulunur. Özel bir kanal belirtmek 400 BAD_REQUEST döndürür.

Hız sınırı anahtarlama¶

Her webhook yolunun kovası, açıklamasındaki yol parametresine (sunucu, kanal veya webhook kimliği) göre anahtarlanır ve o kimliği çağıran herkes tarafından paylaşılır. Yanıt başlıkları Hız sınırları sayfasında açıklanır.

Webhook yürütme, webhook mesajı yolları ve GitHub, Slack ile Instatus yolları genel sınırdan muaftır ve yalnızca kendi kovalarıyla sınırlanır. Kimliği doğrulanmış yönetim yolları genel sınıra da sayılır.

Webhook nesnesi¶

Bir webhook tek bir sunucuya aittir ve o sunucunun tek bir kanalına gönderim yapar. TEBHOS token'ını oluşturma anında bir kez üretir ve hiçbir zaman döndürmez (yenilemez); bu nedenle kimlik ve token çifti, webhook'un ömrü boyunca bir taşıyıcı (bearer) kimlik bilgisidir.

Yapı¶

Örnek¶

{
  "id": "1501314428688998182",
  "guild_id": "1501314428688990000",
  "channel_id": "1501314428688991111",
  "name": "Build bot",
  "avatar": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "token": "Xk3Qw9ZpL2vB7nR4tY6uI8oP0aS1dF5gH2jK4lZ9xC7vB1nM3qW5eR8tY0uI2oP4",
  "user": {
    "id": "1501314428688990001",
    "username": "ada",
    "discriminator": 0,
    "global_name": "Ada",
    "avatar": null,
    "bot": false
  }
}

Token webhook nesnesi¶

Token yolları bu nesneyi döndürür. user dışında webhook nesnesinin tüm alanlarına sahiptir.

Webhook mesajı gövdesi¶

Webhook yürütme işleminin kabul ettiği JSON gövdesi.

Bir mesajın boş olmayan bir content alanına veya en az bir gömmeye ihtiyacı vardır; aksi halde istek 400 CANNOT_SEND_EMPTY_MESSAGE ile başarısız olur.

Bahsetmeler¶

TEBHOS, içerikteki <@id> veya <@!id> biçiminde yazılmış kullanıcı bahsetmelerini ve @everyone / @here ifadelerini ayrıştırır. allowed_mentions yoksa varsayılan {"parse": []} olur: bahsetmeler yine görünür ama kimseye bildirim gitmez. Varsa:

• kullanıcılar, parse users içerdiğinde korunur; users kimlikleri listeliyorsa yalnızca bu kimlikler korunur;
• @everyone ve @here yalnızca parse everyone içerdiğinde korunur;
• boş olmayan bir parse, boş olmayan bir users veya roles listesiyle birlikte gönderilirse istek 400 PARSE_AND_USERS_OR_ROLES_CANNOT_BE_USED_TOGETHER ile reddedilir.

Webhook mesajlarında rol bahsetmeleri çözümlenmez.

Sunucu webhook'ları¶

Sunucu webhook'larını listeleme¶

GET /guilds/{guild_id}/webhooks

Bir sunucudaki webhook nesnelerinden oluşan bir dizi döndürür. Sunucu düzeyinde MANAGE_WEBHOOKS gerektirir. Bir webhook yalnızca çağıran onun kanalında da VIEW_CHANNEL ve MANAGE_WEBHOOKS izinlerine sahipse dahil edilir; kanalı olmayan bir webhook hiçbir zaman dahil edilmez.

Hız sınırı: webhook:list_guild kovasında her sunucu için 10 saniyede 40 istek.

Kanal webhook'ları¶

Kanal webhook'larını listeleme¶

GET /channels/{channel_id}/webhooks

Bir sunucu kanalındaki webhook nesnelerinden oluşan bir dizi döndürür. Sunucu düzeyinde MANAGE_WEBHOOKS ve kanalda VIEW_CHANNEL ile MANAGE_WEBHOOKS gerektirir.

Hız sınırı: webhook:list_channel kovasında her kanal için 10 saniyede 40 istek.

Webhook oluşturma¶

POST /channels/{channel_id}/webhooks

Bir webhook oluşturur ve token'ı dahil yeni webhook nesnesiyle birlikte 200 döndürür. İzinler kanal webhook'larını listelemeyle aynıdır.

JSON gövdesi¶

Bir kanal en fazla 15, bir sunucu en fazla 1,000 webhook tutar; bir tane daha oluşturmak 400 BAD_REQUEST döndürür. Geçersiz bir ad veya görüntü de 400 BAD_REQUEST döndürür.

Yan etkiler¶

Bir WEBHOOK_CREATE sunucu denetim kaydı girişi oluşturur ve sunucuya channel_id ile Webhooks Update yayar.

Hız sınırı: webhook:create kovasında her kanal için dakikada 10 istek.

curl -X POST https://tebhos.com/api/v1/channels/1501314428688991111/webhooks \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Build bot"}'

Webhook yönetimi¶

Webhook alma¶

GET /webhooks/{webhook_id}

Bir webhook nesnesi döndürür. Sunucu düzeyinde ve webhook'un kanalında MANAGE_WEBHOOKS gerektirir.

Hız sınırı: webhook:read kovasında her webhook için 10 saniyede 100 istek.

Webhook güncelleme¶

PATCH /webhooks/{webhook_id}

Bir webhook'u günceller ve değiştirilmiş webhook nesnesini döndürür. İzinler webhook almayla aynıdır.

Değişen alanlarla bir WEBHOOK_UPDATE sunucu denetim kaydı girişi oluşturur ve webhook'un önceki kanalını belirten Webhooks Update yayar.

Hız sınırı: webhook:update kovasında her webhook için 10 saniyede 20 istek.

Webhook silme¶

DELETE /webhooks/{webhook_id}

Bir webhook'u kalıcı olarak siler ve 204 döndürür. İzinler webhook almayla aynıdır. Bir WEBHOOK_DELETE sunucu denetim kaydı girişi oluşturur ve Webhooks Update yayar. Webhook'un daha önce gönderdiği mesajlar kanalda kalır.

Hız sınırı: webhook:delete kovasında her webhook için 10 saniyede 20 istek.

Token yolları¶

Aşağıdaki yollar, yollarındaki webhook kimliğini ve token'ı eksiksiz kimlik bilgisi olarak kabul eder. Webhook ile eşleşmeyen bir token 401 UNAUTHORIZED döndürür; var olmayan bir webhook kimliği 404 NOT_FOUND döndürür.

Token ile webhook alma¶

GET /webhooks/{webhook_id}/{token}

Bir token webhook nesnesi döndürür.

Hız sınırı: webhook:read kovasında her webhook için 10 saniyede 100 istek.

Token ile webhook güncelleme¶

PATCH /webhooks/{webhook_id}/{token}

name ve avatar alanlarını Webhook güncelleme ile aynı kurallarla günceller ve değiştirilmiş token webhook nesnesini döndürür. channel_id göndermek 403 FORBIDDEN döndürür: yalnızca token ile bir webhook taşınamaz. Webhooks Update yayar; denetim kaydı girişi oluşturulmaz.

Hız sınırı: webhook:update kovasında her webhook için 10 saniyede 20 istek.

Token ile webhook silme¶

DELETE /webhooks/{webhook_id}/{token}

Webhook'u kalıcı olarak siler ve 204 döndürür. Webhooks Update yayar; denetim kaydı girişi oluşturulmaz.

Hız sınırı: webhook:delete kovasında her webhook için 10 saniyede 20 istek.

Webhook yürütme¶

POST /webhooks/{webhook_id}/{token}

Webhook'un kanalında, yazarı webhook olan bir mesaj oluşturur. Content-Type: application/json ile bir webhook mesajı gövdesi gönderin.

Sorgu parametreleri¶

Yanıt¶

Yan etkiler¶

Mesaj webhook_id, geçerli ad ve webhook'un saklanan avatarıyla saklanır. Kanalı okuyabilen her oturum, author alanı webhook'tan oluşturulmuş (id = webhook kimliği, bot: true) eksiksiz mesaj nesnesiyle birlikte Message Create alır.

Hız sınırı¶

webhook:execute kovasında her webhook için dakikada 60 istek (Slack webhook'u yürütme ile paylaşılır).

curl -X POST "https://tebhos.com/api/v1/webhooks/1501314428688998182/$WEBHOOK_TOKEN?wait=true" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deploy finished", "embeds": [{"title": "v2.4.0", "color": 3066993}]}'

import os, requests

url = f"https://tebhos.com/api/v1/webhooks/1501314428688998182/{os.environ['WEBHOOK_TOKEN']}"
res = requests.post(url, json={"content": "Deploy finished"})
res.raise_for_status()  # 204 No Content

Webhook mesajı yanıtı¶

wait=true ile Webhook yürütme, Webhook mesajını alma ve Webhook mesajını düzenleme standart mesaj nesnesini döndürür; Gateway'in ilettiği şekille aynıdır. author webhook'tur (id webhook kimliği, username mesajın gönderildiği ad, bot true), webhook_id doludur ve embeds çözümlenmiş medya alanlarıyla saklanan gömmeleri taşır.

Webhook mesajı yolları¶

Bu yollar yalnızca webhook'un kendisinin mevcut kanalına gönderdiği mesajları hedefler. O kanalda bulunmayan bir mesaj 404 UNKNOWN_MESSAGE, başka birinin gönderdiği bir mesaj 403 MISSING_PERMISSIONS döndürür.

Webhook mesajını alma¶

GET /webhooks/{webhook_id}/{token}/messages/{message_id}

Mesaj nesnesini döndürür.

Hız sınırı: webhook:message_get kovasında her webhook için dakikada 60 istek.

Webhook mesajını düzenleme¶

PATCH /webhooks/{webhook_id}/{token}/messages/{message_id}

Bir webhook mesajını düzenler ve güncellenmiş mesaj nesnesini döndürür.

Boş olmayan content, boş olmayan bir embeds listesi veya flags alanlarından en az biri gerekir; aksi halde istek 400 CANNOT_SEND_EMPTY_MESSAGE ile başarısız olur. Sınırları aşan bir gömme alan bazında bildirilir (örneğin yol embeds.0.title, kod STRING_LENGTH_INVALID). İçeriğin değişmesi mesajı düzenlenmiş olarak işaretler ve bahsetmelerini yeniden hesaplar. Message Update yayar.

Hız sınırı: webhook:message_edit kovasında her webhook için dakikada 30 istek.

Webhook mesajını silme¶

DELETE /webhooks/{webhook_id}/{token}/messages/{message_id}

Bir webhook mesajını siler ve 204 döndürür. Message Delete yayar.

Hız sınırı: webhook:message_delete kovasında her webhook için dakikada 30 istek.

Slack webhook'u yürütme¶

POST /webhooks/{webhook_id}/{token}/slack

Slack uyumlu bir yükü kabul eder, TEBHOS içeriğine ve gömmelerine dönüştürür ve yazarı webhook olan tek bir mesaj oluşturur. Sabit ok gövdesiyle (text/html) 200 döndürür.

Slack yük nesnesi¶

Slack eki nesnesi¶

Hiçbir gömme özelliği üretmeyen ek atılır. Ne içerik ne de gömme üreten bir yük 400 BAD_REQUEST döndürür. İçerikteki her bahsetme, allowed_mentions olmadan Webhook yürütme işleminde olduğu gibi korunur. Yükte nonce bulunmadığından tekrarlanan bir çağrı ikinci bir mesaj oluşturur.

Hız sınırı: webhook:execute kovasında her webhook için dakikada 60 istek.

GitHub webhook'u yürütme¶

POST /webhooks/{webhook_id}/{token}/github

Bir GitHub webhook teslimatını kabul eder ve olay işlenebiliyorsa biçimlendirilmiş tek bir mesaj oluşturur. Mesaj oluşturulsa da oluşturulmasa da her zaman 204 döndürür. Bir GitHub deposunun veya kuruluşunun webhook'unu application/json içerik türüyle bu URL'ye yönlendirin.

İstek başlıkları¶

Gövde türsüz JSON olarak okunur; alanları eksik veya bozuk bir teslimat yalnızca hiçbir şey üretmez.

Üretilen mesaj¶

İşlenen bir olay, içeriği olmayan ve tam olarak bir rich gömme içeren tek bir mesaj oluşturur; mesaj GitHub adıyla ve avatarsız gönderilir. Gömme yazarı, aşağıdaki tabloda belirtilen GitHub kullanıcısıdır (giriş adı, profil URL'si ve avatar). Bahsetmeler hiçbir zaman ayrıştırılmaz; bu nedenle bir commit mesajındaki veya yorumdaki hiçbir şey kimseye bildirim göndermez.

Gömme başlıkları kırpılır ve 70 karaktere (sıradan push'lar ile check run/suite'ler için 256) kısaltılır; açıklamalar 350 karaktere kısaltılır ve kesilen yer ... ile işaretlenir. HTML varlıkları (entity) çözülmez.

GitHub olay türleri¶

Her olay ayrıca repository gerektirir. Bir push her commit için bir satır listeler ve bir commit mesajındaki This reverts commit <40-character sha>. cümlesi, geri alınan commit'e giden bir bağlantıya dönüştürülür. Check run ve suite'ler success sonucunda yeşil, aksi halde kırmızı çizilir.

Hız sınırı: webhook:github kovasında her webhook için dakikada 200 istek.

Instatus webhook'u yürütme¶

POST /webhooks/{webhook_id}/{token}/instatus

Bir Instatus durum sayfası bildirimini kabul eder ve yük işlenebiliyorsa biçimlendirilmiş tek bir mesaj oluşturur. Mesaj oluşturulsa da oluşturulmasa da her zaman 204 döndürür.

İşleme¶

TEBHOS şu sırayla tam olarak bir bölüm seçer:

1. Varsa incident. Yalnızca incident.name boş değilse işlenir.
2. Aksi halde, varsa maintenance. Yalnızca maintenance.name boş değilse işlenir.
3. Aksi halde component_update veya component.

Mesajın içeriği yoktur ve bir rich gömme içerir; Instatus adıyla ve avatarsız gönderilir. Bahsetmeler hiçbir zaman ayrıştırılmaz.

Instatus durum değerleri¶

Bir durum, büyük harfe çevrilip A-Z dışındaki her karakter çıkarılarak normalleştirilir; böylece degraded_performance DEGRADEDPERFORMANCE olur.

Diğer tüm değerler değiştirilmeden, nötr renkle üretilir.

Hız sınırı: webhook:instatus kovasında her webhook için dakikada 200 istek.