Webhook'lar

Webhook gizli bir adrestir: ona HTTP isteği gönderen program, Anten’deki bir odaya mesaj yazar. Derleme sunucunuz “derleme bitti” diyebilir, izleme aracınız bir arızayı haber verebilir. Programın Anten’de hesabı olması gerekmez.

Ne işe yarar

Webhook tek yönlüdür: program odaya yazar, ama odadakileri okuyamaz ve kimseye cevap veremez. Mesaj, webhook’a verdiğiniz adla ve BOT etiketiyle görünür.

Program mesaj okuyacak, komutlara cevap verecek ya da sesli odaya girecekse webhook yerine bot hesabı kullanın (bot kılavuzunda).

Webhook oluşturun

1. Odanın ayarlarını açın. Oda listesinde odaya sağ tıklayıp Oda ayarları’nı seçin ya da oda başlığındaki ayar simgesine basın.
2. Entegrasyonlar altında Webhook’lar bölümünü seçin. Bu bölüm yalnızca o odada Webhook’ları yönetme izni olanlara görünür. Yöneticilerde bu izin vardır.
3. Bir ad yazın ve Webhook oluştur’a basın. Ad 1–32 karakter olabilir. Programın mesajları bu adla görünür; örneğin “Derleme”.
4. Gösterilen adresi kopyalayın ve güvenli bir yere kaydedin. Adres yalnızca bu sefer gösterilir. Hemen altında, bu adresle hazırlanmış bir curl komutu da vardır.

Adres şu biçimdedir:

https://anten.example.org/api/v1/webhooks/<id>/<anahtar>

Sondaki anahtar, webhook’un parolasıdır. Adresin tamamını bilen herkes o odaya yazabilir.

İlk mesajı gönderin

1. Adresi bir ortam değişkenine koyun. Örneklerin hepsi adresi ANTEN_WEBHOOK değişkeninden okur; böylece adres kodun içine yazılmaz.

   export ANTEN_WEBHOOK='https://anten.example.org/api/v1/webhooks/<id>/<anahtar>'
   

2. Bir mesaj gönderin. İstek JSON biçimindedir ve tek alanı content’tir.

   curl -H "Content-Type: application/json" -d '{"content":"Derleme tamamlandı"}' "$ANTEN_WEBHOOK"
   

3. Odaya bakın. Mesaj webhook’un adıyla ve BOT etiketiyle görünür. İstek başarılıysa sunucu 200 ve oluşan mesajı döndürür.

Programdan gönderin

İki örnek de yalnızca dilin kendi kütüphanelerini kullanır ve hata olursa durum kodunu ve hatanın kodunu yazar.

Node.js (18 ve üstü)

const res = await fetch(process.env.ANTEN_WEBHOOK, {
	method: 'POST',
	headers: { 'Content-Type': 'application/json' },
	body: JSON.stringify({ content: 'Derleme tamamlandı' })
});
if (!res.ok) {
	const err = await res.json().catch(() => ({}));
	console.error('Webhook hatası:', res.status, err.code);
}

Python

import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["ANTEN_WEBHOOK"],
    data=json.dumps({"content": "Derleme tamamlandı"}).encode(),
    headers={"Content-Type": "application/json"},
)
try:
    urllib.request.urlopen(req)
except urllib.error.HTTPError as e:
    print("Webhook hatası:", e.code, e.read().decode())

Mesajlar ve sınırlar

Ne gönderilebilir

• Yalnızca metin: 1–4000 karakter. Baştaki ve sondaki boşluklar silinir.
• Kalın, italik, kod ve alıntı gibi biçimler diğer mesajlardaki gibi gösterilir. HTML hiçbir zaman işlenmez.
• Dosya, buton ya da kart gönderilemez. İstekte content dışında bir alan varsa istek reddedilir.

Ad

Mesajlar her zaman webhook’un adıyla görünür; ad istekte değiştirilemez. Webhook’a Yeniden adlandır ile yeni bir ad verirseniz, yeni ad yalnızca bundan sonraki mesajlarda görünür. Önceki mesajlar gönderildikleri adla kalır.

Sınırlar

• Bir webhook art arda 10 mesaj gönderebilir, sonra saniyede bir.
• Bir IP adresinden gelen bütün webhook istekleri de sınırlıdır: art arda 30, sonra saniyede 5. Yanlış anahtarlı istekler de bu sayıya girer.
• Sınırı aşan istek 429 alır. Retry-After başlığındaki süre kadar (saniye) bekleyip yeniden deneyin.
• Bir odada en fazla 10 webhook olabilir. İstek gövdesi en fazla 16 KB olabilir.

Mesajlara sonra ne olur

Webhook’un mesajları düzenlenemez. Odada Mesajları yönetme izni olanlar onları silebilir. Webhook silinince gönderdiği mesajlar odada kalır. Webhook’lar listesinde her webhook’un son kullanıldığı zaman da görünür.

Güvenlik

Adresi bir parola gibi saklayın

Adresi bilen herkes, hesabı olmadan o odaya yazabilir. Adresi bir kod deposuna, bir sohbete ya da bir hata kaydına koymayın. Programa bir ortam değişkeniyle ya da kullandığınız sistemin gizli ayarlarıyla verin.

Sunucu anahtarın kendisini değil, yalnızca bir özetini (SHA-256) saklar. Bu yüzden adres sonradan bir daha gösterilemez. Sunucunun kayıtlarına da anahtar yazılmaz.

Adresi yenileyin ya da silin

Adresi kaybettiyseniz ya da sızdığından şüpheleniyorsanız webhook’un yanındaki Adresi yenile’ye basın. Eski adres hemen çalışmayı bırakır ve yeni adres bir kez gösterilir. Programa yeni adresi verin.

Webhook’a artık ihtiyacınız yoksa Sil’e basın. Oluşturma, yeniden adlandırma, adres yenileme ve silme denetim kaydına geçer.

Şifreli odalarda neden çalışmaz

Uçtan uca şifreli bir odada mesajları yalnızca odadakilerin cihazları şifreler ve açar; sunucuda o odanın anahtarı yoktur. Webhook’un mesajını ise sunucu yazar, bu yüzden onu şifreleyemez. Şifresiz bir mesajın şifreli bir odaya girmesine de izin verilmez.

Bu nedenle şifreli bir odada webhook oluşturulamaz. Bir oda sonradan şifreli yapılırsa oradaki webhook’lar 409 room_sealed cevabını alır ve odanın Webhook’lar bölümü bunu bir uyarıyla gösterir.

Başvuru

İstek

POST /api/v1/webhooks/<id>/<anahtar>
Content-Type: application/json

{ "content": "Derleme tamamlandı" }

Oturum ya da başka bir başlık gerekmez. Başarılı istek 200 ve oluşan mesajı JSON olarak döndürür (id, room_id, content, webhook, created_at ve diğer alanlar).

Hata cevapları

Hata cevabının gövdesinde bir code alanı ve kısa bir açıklama (message) bulunur.