Giden webhook'lar

Bu rehberde: OrqLabs'taki olayları (aday nitelendi, gönderi yayınlandı, bütçe uyarısı…) kendi sisteminize anında iletirsiniz. 28 olayın listesi, imza doğrulama kodu ve yeniden deneme kuralları burada. Bu rehber yazılımcılar içindir.

⏱ 15 dakika

Kısaca#

Giden webhook, OrqLabs'ın sizin sisteminize "bir şey oldu" diye haber vermesidir. Örneğin: bir aday nitelendiğinde CRM'inize kayıt açmak veya bir onay istendiğinde Slack'e düğmeli mesaj göndermek. Uç noktayı Ayarlar → Webhook'lar sayfasında tanımlarsınız; OrqLabs her olayı imzalı bir JSON olarak gönderir.

Genel bilgi#

Giden webhook'lar OrqLabs'daki olayları (lead nitelendi, gönderi yayınlandı, konuşma devredildi, bütçe uyarısı…) sizin HTTP uç noktanıza anlık iletir. Üç kullanım yolu vardır:

Bu rehber olay aboneliklerine odaklanır; imza ve zarf üçünde de aynıdır.

Uç nokta oluşturma#

Ayarlar → Webhooks → Yeni uç nokta:

Kaydettikten sonra Test gönder düğmesi ping türünde bir zarf yollar; yanıtınız ve süresi ekranda görünür. Teslim geçmişi (son 7 gün) uç nokta ayrıntısında: durum kodu, deneme sayısı, gövde önizlemesi, Yeniden gönder.

Zarf (PlatformEventEnvelope)#

{
  "id": "evt_01J8Z…",
  "type": "lead.qualified",
  "organizationId": "org_01J…",
  "projectId": "prj_01J…",
  "at": "2026-09-26T09:14:03.120Z",
  "payload": { … olaya özgü … }
}

id teslim başına değil olay başına benzersizdir; yeniden denemelerde aynı id gelir (idempotency anahtarı). projectId proje bağlamı olmayan olaylarda (integration.*, budget.* organizasyon düzeyinde) bulunmaz.

Olaylar (PLATFORM_EVENTS)#

Lead#

Mesajlaşma#

İçerik#

Kampanya#

İş akışı ve ajan#

Analitik#

Entegrasyon#

Onay ve bütçe#

Toplam 28 olay. trigger.event node'unda bunların bir alt kümesi seçilebilir; webhook'lar hepsini alır.

Teslim ve yeniden deneme#

• Teslim webhooks-out kuyruğu üzerinden asenkron yapılır; olay ile teslim arası genellikle < 2 sn.
• İstek: POST, Content-Type: application/json, gövde zarf; zaman aşımı 10 sn.
• Başarı: herhangi bir 2xx. Gövde okunmaz.
• Başarısızlık (bağlantı hatası, zaman aşımı, 3xx/4xx/5xx): üstel geri çekilmeyle 5 deneme (yaklaşık 1 dk, 5 dk, 15 dk, 30 dk sonra; toplam ~1 saat). 410 Gone alınırsa uç nokta otomatik devre dışı bırakılır.
• Ardışık 100 başarısız teslimden sonra uç nokta pasife alınır ve organizasyon sahibine bildirim gider.
• Sıra garantisi yoktur; at alanına göre sıralayın.
• Yük boyutu 256 KB ile sınırlıdır; büyük nesneler (lead, post) kısaltılabilir, …Id alanlarıyla API'den tam kaydı çekin.

İmza başlıkları#

Bu başlık adları OrqLabs'un belgelenen sözleşmesidir; ilk teslimde uç noktanızın loglarından doğrulayın. İmza, X-AgentFlow-Timestamp değeri, bir nokta ve ham gövdenin birleştirilmesiyle ("<timestamp>.<gövde>") hesaplanır; zaman damgası imzaya dahil olduğu için tekrar saldırılarına karşı 5 dakikalık tolerans uygulayın ve id ile idempotency sağlayın.

Doğrulama (Node.js / Express)#

import express from "express";
import crypto from "node:crypto";

const app = express();
const SECRET = process.env.ORQLABS_WEBHOOK_SECRET;
const seen = new Set(); // üretimde Redis/DB kullanın

app.post("/orqlabs/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.get("X-AgentFlow-Signature") ?? "";
  const ts = Number(req.get("X-AgentFlow-Timestamp") ?? 0);

  // 1) Zaman toleransı (5 dk)
  if (Math.abs(Date.now() / 1000 - ts) > 300) return res.status(401).send("stale");

  // 2) HMAC-SHA256: "<timestamp>.<ham gövde>" üzerinden
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(`${ts}.`).update(req.body).digest("hex");
  const a = Buffer.from(sig), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).send("bad signature");

  // 3) Idempotency
  const event = JSON.parse(req.body.toString("utf8"));
  if (seen.has(event.id)) return res.status(200).send("dup");
  seen.add(event.id);

  // 4) Hızlı yanıt, işlemi arka plana al
  res.status(200).send("ok");
  setImmediate(() => handle(event));
});

function handle(event) {
  switch (event.type) {
    case "lead.qualified":
      // CRM'e yaz
      break;
    case "approval.requested":
      // Slack'e onay düğmeli mesaj gönder
      break;
    case "budget.warning":
      // Finans ekibine uyarı
      break;
  }
}

app.listen(3001);

Önemli: express.json() kullanmayın; gövde ayrıştırıldıktan sonra yeniden serileştirilirse imza tutmaz. Ham gövdeyi (express.raw) doğrulayın.

Python (FastAPI) için aynı mantık: hmac.new(secret, f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest() ve hmac.compare_digest.

Örnek senaryolar#

Sık sorulan sorular#

Aynı olay iki kez gelebilir mi? Evet; adresiniz geç yanıt verirse yeniden denenir. Zarftaki id alanıyla tekilleştirin.

İmza neden tutmuyor? İmza ham gövde üzerinden hesaplanır. Gövdeyi JSON olarak ayrıştırıp yeniden serileştirmeyin; "<timestamp>.<ham gövde>" kullanın.

Adresim kapalıyken olaylar kaybolur mu? Yaklaşık 1 saat boyunca 5 kez denenir. Teslim geçmişinden Yeniden gönder ile elle de gönderebilirsiniz.

Sonraki adım#

• Custom Webhook entegrasyonu
• Webhook ve API tetikleyicileri
• SSE olayları
• API anahtarları