AgentVera webhook rehberi

Webhook ne yapar?

Her webhook gizli bir adres alır. Bu adrese gelen bir istek için AgentVera iki şey yapabilir:

• Seçtiğin panoda ve sütunda bir kanban kartı açar; istersen etiket de ekler.
• Bir ajan görevi oluşturur: Claude ya da Codex, ya senin Runner’ında ya da kartın projesini açık tutan masaüstü uygulamasında çalışır.

Ajan turunu bitirince sonucun özeti karta “AgentVera” adıyla iç yorum olarak yazılır. Görevleri app.agentvera.dev/tasks sayfasından canlı izlersin.

Webhook oluşturma

Webhook’ları organizasyon sahipleri ve yöneticileri oluşturur. app.agentvera.dev/webhooks sayfasında “Yeni webhook”a tıkla ve şu adımları izle:

1. Webhook’a bir ad ver.
2. Kart aksiyonu: kartın açılacağı panoyu ve sütunu seç.
3. Görev aksiyonu: ajan türünü (Claude ya da Codex) ve hedefi seç. Hedef belirli bir Runner (istersen çalışma klasörüyle) ya da “Proje” olabilir; Proje, kartın projesini açık tutan masaüstü uygulaması demektir. Proje görevleri her zaman bir karta bağlıdır.
4. Şablon: kart başlığını, açıklamasını ve ajan prompt’unu {{…}} yer tutucularıyla yaz.
5. Filtre (isteğe bağlı): yalnızca belirli isteklerin işlenmesini sağla.
6. İmza (önerilir): GitHub ya da genel HMAC-SHA256 doğrulamasını seç.
7. Kaydet. Webhook adresi ve imza sırrı yalnızca bir kez gösterilir; ikisini de kopyala.

Adresi ya da sırrı daha sonra yenileyebilirsin; eski adres hemen çalışmaz olur.

Şablon ve yer tutucular

Yer tutucular gelen isteğin içinden değer okur:

• {{body.issue.title}}: JSON gövdesindeki alanlar, noktalı yolla. Dizi elemanları için sayı kullanılır: {{body.commits.0.id}}.
• {{headers.x-github-event}}: istek başlıkları, küçük harfle.
• {{query.foo}}: adresteki sorgu parametreleri.

Bulunamayan bir değer boş yazılır; nesneler JSON olarak eklenir. Kart başlığındaki boşluklar tek boşluğa indirilir ve başlık 300 karakterle sınırlanır. Kart açıklaması güvenli hâle getirilir; prompt ise ajana yazdığın gibi gider.

Filtre

Filtre, istekteki bir değerin (path) belirli bir değere eşit olmasını ya da izin verdiğin değerlerden biri olmasını ister. Örneğin yalnızca yeni açılan GitHub issue’ları için path olarak body.action, eşit olduğu değer olarak opened yaz. Filtreye uymayan istekler “ignored” olarak kaydedilir ve kart ya da görev açılmaz.

İmza doğrulama

• GitHub: X-Hub-Signature-256 başlığı imza sırrıyla doğrulanır.
• Genel HMAC-SHA256: gövdenin hex imzası, adını senin belirlediğin başlıkta beklenir; başına sha256= eklenmişse de kabul edilir.

Kaynak imza destekliyorsa her zaman kullan. İmza desteklemeyen kaynaklarda güvenlik gizli adrese dayanır; adres sızarsa yenile.

Örnek: GitHub issue’larından görev

1. GitHub’da depoda Settings → Webhooks → Add webhook’a git.
2. Payload URL olarak AgentVera webhook adresini, Content type olarak application/json’ı, Secret olarak imza sırrını gir.
3. Olay olarak “Issues”ı seç ve kaydet.

AgentVera’daki şablon:

Başlık:   {{body.issue.title}}
Açıklama: {{body.issue.body}}
Filtre:   body.action = opened
Prompt:
GitHub issue #{{body.issue.number}}: {{body.issue.title}}

{{body.issue.body}}

Bu hatayı incele, düzelt ve testleri çalıştır.

Sentry ve diğer JSON kaynakları

Herhangi bir servisi webhook adresine yönlendir. Kaynak imza atabiliyorsa genel HMAC-SHA256 kullan; atamıyorsa gizli adrese güven. Kaynağın gönderdiği alanları yer tutucularla şablona eşle. Kendi sisteminden denemek için:

curl -X POST "https://app.agentvera.dev/hooks/<id>/<gizli>" \
  -H "content-type: application/json" \
  -d '{"title": "Ödeme sayfası 500 veriyor", "detail": "..."}'

İstekler, yanıtlar ve limitler

• Yalnızca POST; gövde JSON ya da form, en fazla 1 MB.
• Webhook başına dakikada 60, IP başına dakikada 600 istek.
• 202: kabul edildi (filtreye uymayan istek de 202 alır).
• 401: imza geçersiz.
• 403: organizasyonun planında webhook yok.
• 404: adres yanlış, webhook kapalı ya da organizasyon askıda (hepsi aynı yanıtı alır).
• 413: gövde çok büyük. 429: limit aşıldı.

Teslimler ve görevler

• Her istek webhook’un “Teslimler” listesine durumuyla kaydedilir: ok, ignored, rejected ya da failed; kart ya da görev açılıp açılmadığı da yazar.
• İstek içeriği (gövde, başlıklar ve sorgu; Authorization, çerez ve imza başlıkları hariç) 7 gün saklanır ve bu sürede güncel şablonla yeniden oynatılabilir; şablonu düzelttikten sonra işe yarar. Süre dolunca içerik silinir, özet kalır.
• app.agentvera.dev/tasks sayfasında görevler canlı izlenir: sırada, alındı, çalışıyor, bitti ya da başarısız. Yöneticiler görevleri iptal edebilir.
• Runner çevrimdışıysa görev sırada bekler ve runner bağlanınca gönderilir. 30 dakika ilerlemeyen bir görev bir kez sıraya döner; ikinci kez olursa başarısız sayılır.

Güvenlik

Webhook içeriği ajanın prompt’una olduğu gibi girer. Bir depoya issue yazabilen biri ajana talimat vermeyi deneyebilir.

• Yalnızca güvendiğin kaynakları ve depoları bağla.
• Filtrelerle hangi isteklerin işleneceğini daralt.
• Runner’da roots ile ajanların erişebileceği klasörleri sınırla.
• Kaynak destekliyorsa her zaman imza kullan; adres bir sırdır, sızarsa yenile.
• İstek içerikleri loglara yazılmaz; loglarda adresin gizli kısmı gizlenir.