Webhook'lar

Webhook'lar, SetGet'te olaylar gerçekleştiğinde dış servislere gerçek zamanlı HTTP bildirimleri göndermenizi sağlar. Bir iş öğesi oluşturulduğunda, yorum gönderildiğinde, döngü başladığında veya izlenen başka bir olay gerçekleştiğinde SetGet, belirttiğiniz URL'ye JSON yükü gönderir. SetGet'i CI/CD boru hatlarına, izleme panolarına, özel botlara veya HTTP geri çağrılarını kabul eden herhangi bir servise bağlamak için webhook'ları kullanın.

Webhook'lar nasıl çalışır

1. SetGet'te bir webhook oluşturup URL, gizli anahtar ve dinlemek istediğiniz olayları belirtirsiniz.
2. Eşleşen bir olay gerçekleştiğinde SetGet, olayı açıklayan bir JSON yükü oluşturur.
3. SetGet, gövdesinde yük ve başlıklarında imza bulunan HTTP POST isteğini URL'nize gönderir.
4. Sunucunuz yükü işler ve HTTP 2xx durum koduyla yanıt verir.
5. İletim başarısız olursa SetGet üstel geri çekilme ile yeniden dener.

Webhook oluşturma

1. Ayarlar > Webhook'lar (çalışma alanı düzeyi) veya Proje Ayarları > Webhook'lar (proje düzeyi) bölümüne gidin.
2. Webhook Oluştur'a tıklayın.
3. Alanları doldurun:

Alan	Zorunlu	Açıklama
URL	Evet	POST isteklerini alacak uç nokta
Gizli anahtar	Önerilir	Doğrulama için yükleri imzalamakta kullanılan paylaşımlı gizli anahtar
Olaylar	Evet	Abone olunacak bir veya daha fazla olay türü
Açıklama	Hayır	Webhook'un amacına ilişkin okunabilir not
Aktif	Evet	Silmeden etkinleştirmek veya devre dışı bırakmak için geçiş

4. Kaydet'e tıklayın.

İPUCU

Her zaman webhook gizli anahtarı belirleyin. Olmadan, gelen isteklerin gerçekten SetGet'ten geldiğini doğrulayamazsınız.

Olay türleri

İş öğesi olayları

Olay	Tetikleyici
work_item.created	Yeni bir iş öğesi oluşturuldu
work_item.updated	İş öğesinin alanları değişti (durum, öncelik, sorumlu, etiketler, tarihler, başlık, açıklama)
work_item.deleted	Bir iş öğesi silindi
work_item.archived	Bir iş öğesi arşivlendi
work_item.unarchived	Bir iş öğesi arşivden geri yüklendi

Yorum olayları

Olay	Tetikleyici
comment.created	Bir iş öğesine yorum eklendi
comment.updated	Bir yorum düzenlendi
comment.deleted	Bir yorum kaldırıldı

Döngü olayları

Olay	Tetikleyici
cycle.created	Yeni bir döngü oluşturuldu
cycle.updated	Döngünün tarihleri, başlığı veya durumu değişti
cycle.started	Döngünün başlangıç tarihine ulaşıldı
cycle.completed	Döngünün bitiş tarihine ulaşıldı veya manuel olarak tamamlandı
cycle.deleted	Bir döngü silindi

Modül olayları

Olay	Tetikleyici
module.created	Yeni bir modül oluşturuldu
module.updated	Modülün alanları değişti
module.deleted	Bir modül silindi

Proje olayları

Olay	Tetikleyici
project.created	Çalışma alanında yeni bir proje oluşturuldu
project.updated	Bir projenin ayarları değişti
project.deleted	Bir proje silindi

Üye olayları

Olay	Tetikleyici
member.invited	Çalışma alanına yeni bir üye davet edildi
member.joined	Davet edilen üye kabul edip katıldı
member.removed	Bir üye çalışma alanından çıkarıldı
member.role_changed	Bir üyenin rolü güncellendi

Etiket olayları

Olay	Tetikleyici
label.created	Yeni bir etiket oluşturuldu
label.updated	Bir etiket yeniden adlandırıldı veya rengi değişti
label.deleted	Bir etiket silindi

Sayfa olayları

Olay	Tetikleyici
page.created	Yeni bir sayfa oluşturuldu
page.updated	Sayfanın içeriği veya başlığı değişti
page.deleted	Bir sayfa silindi

Intake olayları

Olay	Tetikleyici
intake.submitted	Yeni bir intake isteği gönderildi
intake.accepted	Bir intake isteği kabul edildi ve iş öğesine dönüştürüldü
intake.declined	Bir intake isteği reddedildi

Yük formatı

Tüm webhook yükleri aynı JSON yapısını izler:

{
  "event": "work_item.created",
  "timestamp": "2026-03-29T14:30:00Z",
  "workspace": {
    "id": "ws_abc123",
    "slug": "my-workspace"
  },
  "project": {
    "id": "proj_def456",
    "name": "Web App",
    "identifier": "WEB"
  },
  "data": {
    "id": "wi_ghi789",
    "title": "Fix dashboard loading issue",
    "state": "Backlog",
    "priority": "High",
    "assignees": ["alice@example.com"],
    "labels": ["bug", "frontend"],
    "created_at": "2026-03-29T14:30:00Z",
    "updated_at": "2026-03-29T14:30:00Z"
  },
  "actor": {
    "id": "user_jkl012",
    "email": "bob@example.com",
    "display_name": "Bob"
  }
}

Alan açıklamaları

Alan	Tür	Açıklama
event	string	Olay türü (ör. work_item.created)
timestamp	string (ISO 8601)	Olayın gerçekleştiği zaman
workspace	object	Çalışma alanı tanımlayıcıları
project	object	Proje tanımlayıcıları (çalışma alanı düzeyi olaylar için null)
data	object	Olayla ilgili tam varlık verisi
actor	object	Olayı tetikleyen kullanıcı (sistem olayları için null)

Güncelleme yükleri

*.updated olaylarında data nesnesi bir changes alanı içerir:

{
  "event": "work_item.updated",
  "data": {
    "id": "wi_ghi789",
    "title": "Fix dashboard loading issue",
    "changes": {
      "state": {
        "old": "Backlog",
        "new": "In Progress"
      },
      "assignees": {
        "old": [],
        "new": ["alice@example.com"]
      }
    }
  }
}

Webhook iletimi

İstek formatı

SetGet, webhook'ları aşağıdaki başlıklarla HTTP POST istekleri olarak gönderir:

Başlık	Değer
Content-Type	application/json
X-SetGet-Event	Olay türü (ör. work_item.created)
X-SetGet-Signature	Yük gövdesinin HMAC-SHA256 imzası
X-SetGet-Timestamp	İletim girişiminin Unix zaman damgası
X-SetGet-Delivery-ID	Bu iletim için benzersiz tanımlayıcı
User-Agent	SetGet-Webhook/1.0

Yeniden deneme politikası

Uç noktanız 10 saniye içinde HTTP 2xx durum koduyla yanıt vermezse SetGet yeniden dener:

Girişim	Başarısızlık sonrası bekleme
1. yeniden deneme	1 dakika
2. yeniden deneme	5 dakika
3. yeniden deneme	30 dakika
4. yeniden deneme	2 saat
5. yeniden deneme	12 saat

5 başarısız yeniden denemeden sonra (toplamda 6 girişim) iletim başarısız olarak işaretlenir. Sürekli başarısız olan webhook'lar, 3 ardışık olay tüm yeniden denemeleri geçtikten sonra otomatik olarak devre dışı bırakılır.

UYARI

Uç noktanızın 10 saniye içinde yanıt verdiğinden emin olun. Uzun süren işlemler, 200 yanıtı gönderdikten sonra eş zamansız olarak gerçekleştirilmelidir.

İletim sıralaması

Webhook iletileri, olayların gerçekleşme sırasına göre gönderilir; ancak ağ koşulları ve yeniden denemeler nedeniyle uç noktanız bunları sırasız alabilir. Doğru sırayı belirlemek için timestamp alanını kullanın.

Webhook'ları test etme

Yerleşik test

1. Webhook yapılandırma sayfasına gidin.
2. Test Gönder'e tıklayın.
3. SetGet, URL'nize örnek verilerle bir test olayı gönderir.
4. Yanıtı görmek için iletim günlüğünü kontrol edin.

Genel inceleme aracı kullanma

İlk testler için, webhook'u üretim uç noktanıza yönlendirmeden önce yükleri yakalamak ve incelemek üzere https://webhook.site veya https://requestbin.com gibi bir servis kullanın.

Webhook kayıtları

Her webhook iletimi günlüğe kaydedilir. Günlükleri görüntülemek için:

1. Ayarlar > Webhook'lar veya Proje Ayarları > Webhook'lar'a gidin.
2. Webhook'a tıklayın.
3. İletim Günlüğü sekmesini açın.

Her günlük girişi şunları gösterir:

Sütun	Açıklama
Olay	Olay türü
Durum	Başarılı (2xx), başarısız veya yeniden deneme bekliyor
Yanıt kodu	Uç noktanızın döndürdüğü HTTP durum kodu
Zaman damgası	İletim girişiminin zamanı
Süre	Milisaniye cinsinden yanıt süresi
İletim Kimliği	İzleme için benzersiz tanımlayıcı

Tam istek yükünü ve yanıt gövdesini görmek için günlük girişine tıklayın.

İPUCU

Entegrasyon sorunlarını ayıklamak için iletim günlüklerini kullanın. Uç noktanız 4xx veya 5xx hatası döndürürse yanıt gövdesi günlükte yakalanır.

Webhook düzenleme

1. Webhook listesine gidin.
2. Düzenlemek istediğiniz webhook'a tıklayın.
3. URL, gizli anahtar, olaylar veya aktif durumu değiştirin.
4. Kaydet'e tıklayın.

Değişiklikler gelecekteki olaylar için hemen geçerli olur.

Webhook silme

1. Webhook listesine gidin.
2. Webhook'un yanındaki Sil düğmesine (veya çöp kutusu simgesine) tıklayın.
3. Silme işlemini onaylayın.

Bir webhook'u silmek gelecekteki tüm iletileri durdurur ve iletim günlüğü geçmişini kaldırır.

Güvenlik -- İmza doğrulama

Her webhook isteği, HMAC-SHA256 imzası içeren bir X-SetGet-Signature başlığı içerir. İsteğin SetGet'ten geldiğini doğrulamak için bu imzayı sunucunuzda kontrol edin.

Doğrulama adımları

1. X-SetGet-Signature başlık değerini çıkarın.
2. Webhook gizli anahtarınızı anahtar olarak kullanarak ham istek gövdesinin HMAC-SHA256'sını hesaplayın.
3. Hesaplanan imzayı başlık değeriyle sabit zamanlı bir karşılaştırma işleviyle karşılaştırın.
4. Eşleşirlerse istek gerçektir. Eşleşmezse reddedin.

Örnek (Go)

func verifySignature(body []byte, secret, signature string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}

Örnek (Node.js)

const crypto = require("crypto");

function verifySignature(body, secret, signature) {
  const expected = crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

UYARI

Üretimde imza doğrulamasını asla atlamamayın. Olmadan, webhook URL'nizi bilen herhangi bir taraf sahte olaylar gönderebilir.

En iyi uygulamalar

• HTTPS kullanın — Yük ele geçirilmesini önlemek için her zaman HTTPS uç noktası kullanın.
• Hızlı yanıt verin — Hemen 200 döndürün ve yükü eş zamansız olarak işleyin.
• Yinelemeleri yönetin — Aynı olay iki kez alınırsa tekilleştirmek için X-SetGet-Delivery-ID başlığını kullanın.
• Gizli anahtarları döndürün — Webhook gizli anahtarınızı periyodik olarak değiştirin ve SetGet'te güncelleyin.
• İletim günlüklerini izleyin — Otomatik devre dışı bırakılmadan önce başarısız webhook'ları tespit etmek için günlükleri düzenli olarak kontrol edin.

İlgili sayfalar

• Entegrasyonlara genel bakış
• İş öğeleri
• Döngüler
• Modüller