Webhook görevleri: imza doğrulama ve güvenli entegrasyon

Webhook görevi, belirlediğin zamanlamayla kendi HTTPS adresine imzalı bir JSON isteği gönderir. Böylece site durumlarını kendi izleme sistemine, iç panellerine ya da mesajlaşma araçlarına aktarabilirsin. İsteğin gerçekten LLCBullet'ten geldiğini anlamak için her istek bir HMAC-SHA256 imzası taşır. Bu yazıda görevin kurulumunu ve imzanın nasıl doğrulanacağını anlatıyoruz.

Görevi oluşturmak

1. Panelde Otomasyon sayfasında yeni görev oluştur ve tür olarak Webhook'u seç.
2. Altyapıyı ve istersen belirli siteleri seç.
3. Webhook adresini yaz. Adres https:// ile başlamalı; port, kullanıcı adı ya da parola içeremez.
4. Site listesinin istek gövdesine eklenip eklenmeyeceğini seç ve zamanlamayı belirle (en sık 5 dakikada bir).
5. Görev oluşturulunca gösterilen webhook gizli anahtarını (whsec_ ile başlar) hemen kaydet. Bu anahtar yalnızca bir kez gösterilir.

Güvenlik nedeniyle istekler yalnızca herkese açık adreslere gönderilir; yerel ya da özel ağ adreslerine çözülen alan adları reddedilir ve yönlendirmeler izlenmez.

İstek gövdesi ve başlıklar

Her istek POST yöntemiyle, JSON gövdeyle gönderilir. Gövdedeki alanlar:

• id: Teslimat kimliği. Çalıştırma ve deneme numarasından oluşur.
• type: Her zaman "automation.webhook".
• task: Görevin kimliği.
• scheduledFor: Çalıştırmanın planlandığı zaman.
• infrastructure: Görevin bağlı olduğu altyapı.
• sites: Site listesi açıksa her site için kimlik, ad, son erişilebilirlik durumu ve yanıt süresi.

İstekle birlikte iki başlık gelir: X-LLCBullet-Signature imzayı, X-LLCBullet-Delivery ise teslimat kimliğini taşır. İmza başlığı "t=zaman,v1=imza" biçimindedir. İmza, gizli anahtarla şu metin üzerinden hesaplanır: Unix zaman damgası, bir nokta ve ham istek gövdesi. Sonuç küçük harfli onaltılık (hex) olarak yazılır.

İmzayı doğrulamak

Aşağıdaki Node.js örneği imzayı doğrular. Gövdeyi JSON'a çevirmeden önceki ham baytlarla çalışman önemlidir; gövde yeniden biçimlendirilirse imza tutmaz.

import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.LLCBULLET_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SECONDS = 300;

// rawBody: isteğin JSON'a çevrilmeden önceki ham baytları (Buffer)
export function verifySignature(rawBody, header) {
  if (typeof header !== "string") return false;
  const parts = Object.fromEntries(
    header.split(",").map((part) => part.trim().split("="))
  );
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) {
    return false;
  }
  const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (age > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", SECRET)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest();
  const provided = Buffer.from(parts.v1, "hex");
  return provided.length === expected.length && timingSafeEqual(provided, expected);
}

• Karşılaştırmayı sabit süreli yap; yukarıdaki örnek bunun için timingSafeEqual kullanır.
• Zaman damgası çok eskiyse isteği reddet. Örnekte 5 dakikalık tolerans kullandık; sunucu saatinin doğru olduğundan emin ol.
• İmza tutmazsa 401 dön ve gövdeyi işleme.

Kurulumu test etmek

Zamanlamanın gelmesini beklemeden entegrasyonu denemek için görevi Otomasyon sayfasından elle çalıştırabilirsin. Çalıştırma geçmişinde her teslimatın sonucunu görürsün; başarısız denemelerde hata mesajı, karşı tarafın döndüğü HTTP kodunu da içerir. İlk denemede imza doğrulaması başarısız olursa en sık neden, gövdenin ham hali yerine JSON'a çevrilip yeniden yazılmış halinin kullanılmasıdır; ikinci sık neden ise gizli anahtarın eksik kopyalanmasıdır. Anahtarın tamamını, whsec_ öneki dahil kullan.

Yanıt, yeniden deneme ve tekrarlar

2xx durum kodlarından biriyle yanıt verdiğinde teslimat başarılı sayılır. Başka bir kod dönerse ya da istek zaman aşımına uğrarsa çalıştırma artan bekleme süreleriyle yeniden denenir; tüm denemeler başarısız olursa "Otomasyon görevi başarısız" bildirimi alırsın. İstek başına bekleme süresi en fazla 30 saniyedir.

• Hızlı yanıt ver: isteği kuyruğa al, 200 dön ve asıl işlemeyi arka planda yap.
• Yeniden denemelerde teslimat kimliği deneme numarasıyla değişir. Aynı çalıştırmanın tekrarlarını ayıklamak için task ve scheduledFor alanlarını birlikte kullan.
• Gizli anahtarı kaynak koduna değil, ortam değişkenine ya da gizli değer yöneticisine koy.
• Anahtarın sızdığından şüpheleniyorsan görevi sil ve yeni bir görev oluşturarak yeni anahtar al.

Sonuç

Webhook görevleri, LLCBullet verisini kendi sistemlerine taşımanın en esnek yolu. İmzayı her istekte doğrula, eski istekleri reddet ve hızlı yanıt ver. Panelden veri çekmek ya da görev tetiklemek istersen kişisel API anahtarları rehberine göz at.

Panelde webhook kur