Webhooks

Webhook, bir şey olduğunda Blesyum'un senin sunucuna POST atmasıdır. Sürekli sorgulamak (polling) yerine olayı beklersin.

#Abonelik

Panel → Geliştirici → Webhooks → Yeni uç

İki şey verirsin: adres ve dinlemek istediğin olaylar. Karşılığında bir imza sırrı alırsın (whsec_ önekli) — bu bir kez gösterilir.

Katalog lisansına göre daralır: aboneliğinde olmayan bir modülün olayı listede görünmez. Seçilebilen ama asla gelmeyecek bir olay, sessizce kaçırılan bir olaydır.

#Teslimat isteği

POST /senin-ucun HTTP/1.1
Content-Type: application/json
X-Blesyum-Event: conversation.created
X-Blesyum-Delivery: 0193c4e2-…
X-Blesyum-Signature: 5f3a9c…

#İmzayı DOĞRULA

Bu adım isteğe bağlı değildir: adresini bilen herkes sana istek atabilir.

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

export function imzaGecerli(hamGovde: string, imza: string, sir: string): boolean {
  const beklenen = createHmac("sha256", sir).update(hamGovde).digest("hex");
  const a = Buffer.from(beklenen, "utf8");
  const b = Buffer.from(imza, "utf8");
  // Uzunluk farklıysa timingSafeEqual FIRLATIR; önce uzunluğu karşılaştır.
  if (a.length !== b.length) return false;
  // 🔴 Düz `===` KULLANMA: karşılaştırma süresi eşleşen karakter sayısına göre
  //    değişir ve saldırgan imzayı bayt bayt tahmin edebilir.
  return timingSafeEqual(a, b);
}

import hmac, hashlib

def imza_gecerli(ham_govde: bytes, imza: str, sir: str) -> bool:
    beklenen = hmac.new(sir.encode(), ham_govde, hashlib.sha256).hexdigest()
    return hmac.compare_digest(beklenen, imza)

#Yanıtın önemli

• 2xx dön — teslimat başarılı sayılır.
• Hızlı dön. İşi kuyruğa at, 200 dön; uzun süren bir işlem zaman aşımına düşer ve olay yeniden denenir.
• 2xx dışı her şey başarısızlıktır ve yeniden denenir.

Üst üste başarısız olan bir uç geçici olarak devre dışı bırakılır; panelde neden başarısız olduğunu (durum kodu ve hata metni) görürsün.

#Mükerrer teslimat

Ağ belirsizdir: 200 döndürdüğün bir olay yeniden gelebilir. X-Blesyum-Delivery kimliğini sakla ve daha önce gördüğünü yok say. Bu, en-az-bir-kez teslimat modelinin doğal sonucudur ve senin tarafında çözülür.

#Test ortamı

test ortamındaki bir API anahtarı canlı yan etkileri tetiklemez: webhook teslimatı yapılmaz. Entegrasyonunu gerçek veriyle ama sessizce deneyebilirsin.

#Olaylar

Katalog panelde ve GET /api/v1/webhooks/catalog ucunda. CRM olaylarından bazıları: