Giden bağlantılar (webhook)

Giden bağlantı, Orbi'de bir şey olduğunda sizin belirlediğiniz bir adrese haber gönderir. Kart açıldığında, koleksiyona kayıt yazıldığında ya da bir koşu bittiğinde kendi sisteminiz — CRM'iniz, sohbet aracınız, otomasyon platformunuz — bunu anında öğrenir ve kendi işini yapar.

Bu, dışarıya doğru olan yöndür. Dışarıdan gelen bir olayın Orbi'de bir akışı başlatmasını istiyorsanız Akışlar sayfasındaki gelen tetikleyiciye bakın.

#Bağlantı eklemek

Ayarlar › Entegrasyonlar altında Webhook ekle düğmesiyle eklenir. Bunu yalnız yöneticiler yapabilir: dışarıya açılan bir adres, workspace'in tamamını ilgilendiren bir karardır.

Eklerken dört şey belirlersiniz:

1. Adres: isteğin gideceği https:// adresi.
2. Olaylar: hangi olayların gönderileceği. Listeden istediğiniz kadarını seçebilirsiniz.
3. Daraltma: isteğe bağlı. Yalnız belirli panoların kartlarını, yalnız belirli koleksiyonların kayıtlarını, ya da yalnız insanların (veya yalnız ajanların) yaptığı değişiklikleri gönderebilirsiniz. Hiçbir kutu işaretlenmezse hepsi gönderilir. Dosya olayları pano süzgecine takılmaz, çünkü dosya bir panoya değil bir alana aittir; gövdedeki spaceId dosyanın alanını söyler.
4. Kapalı alanlar: isteğe bağlı. Genel'in ve açık alanların olayları her zaman gönderilir. Kapalı bir alanın olayları ise yalnız bu listede işaretlenirse gider. Listede yalnız üyesi olduğunuz kapalı alanlar çıkar. Başka birinin işaretlediği, sizin görmediğiniz bir alan kaydettiğinizde işaretli kalır. Kapalı bir alanı bir webhook'a açmak Denetim sekmesine yazılır.

Kaydettiğiniz anda bir sır (secret) gösterilir. Bu sır bir daha gösterilmez; kaydedin. İsteğin gerçekten Orbi'den geldiğini bu sırla doğrulayacaksınız.

#Hangi olaylar var?

Dört olay eski adlarıyla listede durmaya devam eder: task.done, task.review, task.error ve schedule_job.completed. Bunlar ilk sürümden kalma adlardır ve çalışmayı sürdürür — kurduğunuz bir entegrasyon bizim adlandırmamız değiştiği için susmaz. Yeni bir bağlantı kuruyorsanız task.state_changed ile flow_run.completed aynı olayları daha fazla bilgiyle taşır.

#Gelen isteğin gövdesi

Her istek aynı kabuğu taşır; olaya göre değişen tek şey data alanıdır.

{
  "id": "9f1c…",
  "type": "task.state_changed",
  "version": 1,
  "occurredAt": "2026-09-04T09:12:03.000Z",
  "workspaceId": "…",
  "actor": { "type": "user", "id": "…", "name": "İbrahim" },
  "data": {
    "taskId": "…",
    "taskNumber": 128,
    "title": "Fatura ekranındaki hata",
    "state": "review",
    "previousState": "in_progress",
    "projectId": "…",
    "projectName": "Ürün"
  }
}

actor olayı kimin yaptığını söyler: bir kişi (user), bir ajan (agent), dış bir sistem (external) ya da Orbi'nin kendisi (system).

Bir kartın koşusunu süren Orbi süreci yarıda kapanırsa koşuyu başka bir süreç devralır ve iş kaldığı yerden sürer. Bu durumda iki olay gelir: agent_run.completed eski koşunun runId'sini ve "status": "taken_over" değerini taşır, ardından gelen agent_run.started ise resumedFromRunId alanında eski koşunun kimliğini taşır. İki koşuyu bu alanla birbirine bağlayabilirsiniz.

Başlıklarda şunlar gelir:

Gövdeye yeni alanlar eklenebilir; bu kırıcı bir değişiklik sayılmaz, bu yüzden alıcı tarafta tanımadığınız alanları yok sayın. Bir alanın kaldırılması ya da anlamının değişmesi gerekirse version artar ve eski sürüm bir süre gönderilmeye devam eder.

#İmzayı doğrulamak

İmza, sırla zaman.gövde metni üzerinden üretilir. Alıcı tarafta yapılacak doğrulama:

const crypto = require('crypto');

function verify(req, secret) {
  const timestamp = req.headers['x-orbi-timestamp'];
  const signature = req.headers['x-orbi-signature'];
  // Ham gövde şart: JSON'a çevrilip yeniden metne dönen bir gövde
  // imzayı bozar (alan sırası ve boşluklar değişir).
  const raw = req.rawBody.toString('utf8');

  // Tekrar saldırısı penceresi: beş dakikadan eski bir istek reddedilir.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${raw}`).digest('hex');
  // Virgülle ayrılmış birden çok imza gelebilir (sır döndürme penceresi).
  return signature.split(',').some((value) =>
    crypto.timingSafeEqual(Buffer.from(value.trim()), Buffer.from(`sha256=${expected}`)),
  );
}

İki nokta önemlidir: gövdeyi ham haliyle imzalayın ve zaman damgası çok eskiyse isteği reddedin. İkincisi olmadan, kaydedilmiş eski bir istek size tekrar gönderilebilir.

#Sırrı değiştirmek

Uca tıklayınca açılan panelde Sırrı döndür düğmesi yeni bir sır üretir ve bir kez gösterir. Eski sır 24 saat daha geçerli kalır ve bu süre boyunca her istek iki imzayla gelir — alıcı sisteminizi acele etmeden güncelleyebilirsiniz. Süre dolduğunda eski imza gönderilmez.

#Teslimat günlüğü

Uç listesinde her satır bir adrestir: kaç olaya abone olduğu ve daraltması satırda yazar. Satıra tıklayınca ucun paneli açılır; abone olunan olaylar, teslimat günlüğü ve bütün eylemler (düzenle, test gönder, sırrı döndür, duraklat, sil) oradadır.

Paneldeki Teslimat logu son teslimatları gösterir: durum, kaçıncı deneme, alıcının döndürdüğü HTTP kodu ve isteğin ne kadar sürdüğü. Ayrıntı ile gönderilen gövdeyi ve alıcının yanıtını olduğu gibi görebilirsiniz — "neden gitmedi" sorusunun cevabı çoğu zaman burada durur.

Alıcı 2xx dönmezse istek üç kez daha denenir (1 dakika, 5 dakika, 30 dakika sonra). Hepsi başarısız olursa teslimat başarısız olarak kalır ve elle gönderebilirsiniz: tek satır için Yeniden gönder, hepsi için Başarısızları yeniden gönder. Yeniden gönderilen istek aynı olaydır — olay kimliği değişmez, yani alıcı tarafta tekilleştirme çalışmaya devam eder.

Test gönder düğmesi orbi.test tipinde örnek bir istek yollar. Gerçek bir olay adı taşımaz, çünkü test isteği sizin otomasyonunuzu gerçek sanıp çalıştırmamalı.

#Bağlantı duraklarsa

Art arda beş teslimat başarısız olursa bağlantı otomatik olarak duraklatılır ve yöneticilere bildirim gider. Bu bir silme değildir: seçtiğiniz olaylar ve daraltmalar yerinde durur. Adresi düzelttikten sonra Yeniden aç ile kaldığı yerden devam eder; ilk başarılı teslimatta sayaç sıfırlanır.

Duraklatma olmasaydı ölü bir adrese saatlerce istek göndermeye devam ederdik ve siz bunu hiç öğrenmezdiniz.

#Sınırlar

• Bir adrese dakikada en fazla 60 istek gönderilir. Toplu bir işlem daha fazla olay üretirse kalanlar bir sonraki dakikaya aktarılır, kaybolmaz.
• İç ağ adresleri (localhost, özel IP aralıkları) kabul edilmez.
• Yönlendirme (3xx) takip edilmez; adresi son haliyle yazın.
• İstek 10 saniyede yanıt gelmezse başarısız sayılır.

Olayların tam listesi ve diğer sistem sınırları için Hızlı referans sayfasına bakabilirsiniz.