CRM webhook nasıl kurulur: bir paketin anatomisi, imzadan teslimat günlüğüne

CRM webhook kurmak, bir kayıt oluşturulduğunda, güncellendiğinde ya da silindiğinde kaydın JSON olarak sizin verdiğiniz adrese anında gönderilmesini sağlamaktır. Ohana360'ta bu iş Kurulum > Webhook'lar ve API ekranında dört adımda biter: ad, hedef adres, obje ve olay seçilir; imza anahtarı dış sisteme kaydedilir; Test Gönder ile deneme paketi yollanır; sonuç Teslimatlar tablosunda okunur.

Ohana360, satış, servis ve finans kayıtlarını tek veritabanında tutan bir iş bulutudur; webhook, bu bulutun dışarıya haber verme yoludur. Özellik listesi yerine tek bir paketi izliyoruz. Özel mobilya üreten Boran Mobilya'nın satış sorumlusu Selin Arda 15 Ekim sabahı "Vadi Konakları showroom" fırsatını Kazanıldı aşamasına çekti. Beş saniye içinde muhasebe yazılımına bağlı bir Make senaryosuna imzalı bir paket ulaştı ve orada fatura taslağı açıldı. Aşağıda o paketin anatomisi, sonra aynı sabahın teslimat günlüğünden beş teşhis.

Webhook nedir, Ohana360'ta nerede kurulur?

Webhook, Ohana360'ın bir kayıt olayında dış sisteme kendiliğinden POST isteği atmasıdır; dış sistemin Ohana360'a sorması gereken REST API'nin tersidir. Kurulum > Entegrasyonlar > Webhook'lar ve API ekranında Yeni Webhook düğmesi beş alanlı bir pencere açar ve Boran Mobilya'nın ilk webhook'u iki dakikada kuruldu:

• Ad. Kendiniz için bir isim: "Muhasebe bildirimi". Zorunludur.
• Obje. Tüm objeler ya da tek obje: lisanslı standart objeler (Şirket, Kişi, Müşteri Adayı, Fırsat, Talep, Görev, Etkinlik, Kampanya, Sipariş, Fatura ve diğerleri) ve özel objeler listede çıkar. Selin Fırsat'ı seçti.
• Hedef URL. Paketin gideceği adres: Make ya da Zapier'den alınan Catch Hook adresi ya da kendi servisiniz. Adres http ya da https ile başlamalıdır; localhost ve iç ağ adresleri sunucu tarafında reddedilir.
• Olaylar. Oluşturma, Güncelleme, Silme; en az biri seçilir. Fırsat kazanılması bir güncellemedir, Selin yalnız Güncelleme'yi işaretledi.
• İmza anahtarı. whs_ ile başlayan anahtar pencerede hazır gelir; Kopyala ile alınıp dış sisteme bir kez kaydedilir, Yenile ile değiştirilir.

Kaydet'ten sonra satır listede Aktif rozeti, obje çipi ve olay çipleriyle görünür; satırdaki kutu webhook'u göndermeden pasife alır. Ekranın üstünde dört sayaç durur: aktif webhook, başarılı teslim, başarısız teslim ve olay türleri. Aynı sayılar Kurulum > Otomasyonlar ve Entegrasyonlar sayfasındaki Dış Sistemler kartında "Webhook Teslimleri (başarılı / toplam)" olarak da okunur. Webhook ekranını yalnız Kurulum'a girebilen yönetici kullanır; Test Gönder ve Teslimatlar sunucuda yönetici kontrolünden geçer.

Bir webhook paketinin içinde ne var?

Paket, dört başlık ve beş alanlı bir JSON gövdeden oluşur: event, obj, record, orgId ve sentAt. Yukarıdaki görsel Selin'in fırsatı için giden paketin kendisidir; satır satır okuyalım.

1. POST satırı ve Content-Type. Paket her zaman POST ile ve application/json gövdeyle gider; sorgu parametresi ya da form alanı yoktur.
2. X-Ohana-Signature. sha256= önekiyle gövdenin HMAC-SHA256 imzası. Bir sonraki bölümün konusu.
3. User-Agent. Ohana360-Webhook/1.0. Sunucu günlüklerinde paketi ayırt etmenin en kolay yolu budur.
4. event. record.created, record.updated ya da record.deleted. Paket hangi alanın değiştiğini söylemez; Kazanıldı'ya çekilen fırsat da, tutarı düzeltilen fırsat da record.updated ile gelir. Karşı taraf record.stage alanına bakarak karar verir.
5. obj. Kaydın obje adı: opportunity, lead, case, account, contact, invoice ya da cobj_ ile başlayan özel obje anahtarı. Değerler arayüz dilinden bağımsızdır.
6. record. Kaydın son hali, bütün alanlarıyla: ad, aşama, tutar, sahip, şirket bağlantısı ve cf_ ile başlayan özel alanlar. Aşama verisi Türkçe arayüzde Kazanıldı görünse de pakette "Closed Won" olarak gider, çünkü fırsat aşamaları veride İngilizce saklanır. Eski değer pakete girmez; silme olayında ise kaydın silinmeden önceki hali gönderilir.
7. orgId ve sentAt. Org numarası ve UTC zaman damgası. Make senaryosu paketi 08:41 UTC, yani Türkiye saatiyle 11:41'de aldı.

Gövde her yazımda sunucuda üretilir; tarayıcıdaki uygulama paketi görmez ve imza anahtarına dokunmaz. Bu yüzden Selin'in bilgisayarı kapansa da teslim yapılır: yazım veritabanına işlenir, yanıt Selin'e döner, paket ondan sonra gönderilir.

Paketin gerçekten Ohana360'tan geldiği nasıl doğrulanır?

Ohana360, paketin ham gövdesini webhook'un imza anahtarıyla HMAC-SHA256'dan geçirir ve sonucu X-Ohana-Signature başlığına yazar; karşı taraf aynı anahtarla aynı hesabı yapar ve iki değeri karşılaştırır. Boran Mobilya'nın muhasebe tarafında çalışan küçük bir Node servisi bunu tek satırla yapıyor: gövdenin HMAC'ini hesaplar, sha256= önekini atıp başlıkla kıyaslar, eşit değilse paketi 401 ile reddeder.

İmza hesabı ham gövdeyle yapılır; JSON'u önce ayrıştırıp yeniden yazan bir servis boşluk ve alan sırası değiştiği için farklı bir sonuç bulur ve her paketi reddeder. Anahtar değiştiğinde iki taraf birlikte güncellenir: Yenile düğmesi Ohana360'taki anahtarı değiştirir, dış sistemdeki kopya elle yenilenir. Make ve Zapier gibi araçlar imzayı kendiliğinden doğrulamaz; o senaryolarda adres gizli tutulur ve istenirse senaryo içinde bir HMAC adımı eklenir. Kurulumu denemenin yolu Test Gönder'dir: event değeri ping, obj değeri test ve "Ohana360 webhook testi" adlı tek kayıtla imzalı bir paket gider, sonuç saniyeler içinde toast olarak ve Teslimatlar'da ilk satır olarak görünür.

Hangi kaydetmeler webhook üretir, hangileri üretmez?

Webhook, kaydı veritabanına işleyen her yoldan üretilir: ekranda Kaydet, satır içi düzenleme, toplu güncelleme, içe aktarma, REST API yazımı, Web-to-Lead ve Web-to-Case formu. Sunucu eski ve yeni kopyayı karşılaştırıp olay listesini çıkarır; aynı liste takip bildirimlerini ve alan geçmişini de besler. Boran Mobilya'nın bir haftası:

Yirmi sınırı, dış sistemi bir içe aktarmada yüzlerce istekle boğmamak içindir; toplu veri taşımada webhook yerine aktarım bittikten sonra REST API ile listeleme kullanılır. Paket yalnız aktif ve geçerli adresli webhook'lara gider; pasife alınan webhook için olay üretilmez ve sonradan açılınca geriye dönük gönderim yapılmaz.

Koşullu gönderim nasıl yapılır: Kurulum webhook'u mu, akış aksiyonu mu?

Kurulum'daki webhook tanımı obje ve olay seçer ama koşul almaz; "yalnız kazanılınca gönder" gibi bir kural için Kurulum > Akışlar'da kayıt tetikli akış kurulur ve aksiyon olarak Webhook Çağır seçilir. Selin ilk hafta Fırsat objesinde Güncelleme olayını açık bırakmıştı; muhasebe her tutar düzeltmesinde paket aldı ve Make senaryosu record.stage alanına bakarak eleme yapmak zorunda kaldı. İkinci hafta iki yolu ayırdı:

• Kurulum webhook'u. Koşulsuz ve objeye bağlı. Dış sistem her olayı görmek istiyorsa (yedek, veri ambarı, arama dizini) doğru yol budur. Pakette __flow alanı yoktur.
• Akış aksiyonu Webhook Çağır. Akış Fırsat objesinde Güncellendiğinde tetiklenir, koşul Aşama eşittir Kazanıldı; aksiyon listesinden Webhook Çağır seçilir ve Kurulum'da tanımlı webhook'lardan biri işaretlenir. Webhook daha önce tanımlanmamışsa aksiyon "Önce Kurulum > Webhook'lar'da bir webhook tanımlayın" der. Bu yoldan giden paketin olayı her zaman record.updated'dır ve gövdeye akışın adını taşıyan __flow alanı eklenir; webhook'un obje ve olay seçimi bu gönderimde dikkate alınmaz, pasif olsa bile gider.

Aksiyon sunucuda koşar: akış tarayıcıda tetiklense bile paket sunucu tarafından imzalanıp gönderilir ve koşu Kurulum > Akışlar > Koşu Geçmişi'nde 90 gün görünür. Zamanlanmış akışta da aynı aksiyon vardır; "üç gün Beklemede kalan siparişleri her sabah dış sisteme bildir" bu yolla kurulur. Akışın koşul ve aksiyon mantığı otomatik hatırlatma rehberinde anlatılıyor.

Teslimat günlüğü nasıl okunur?

Teslimatlar tablosu sunucunun yaptığı her gönderimi zaman, olay, obje, adres ve HTTP koduyla listeler; yeşil rozet 2xx alındı demektir, kırmızı rozet ise adres yanlış, servis kapalı, imza reddedilmiş ya da 5 saniyede cevap gelmemiş demektir. Org başına son 100 teslim saklanır, ekranda son 50 gösterilir ve Yenile düğmesiyle tazelenir. Boran Mobilya'nın 15 Ekim sabahında beş satır vardı:

Günlük bir teşhis aracıdır, kurtarma aracı değil. Gönderilen gövde ve karşı tarafın cevap metni saklanmaz; satır yalnız kodu gösterir. Başarısız teslim yeniden denenmez ve zil bildirimi üretmez, webhook da kendiliğinden kapanmaz; 404 veren Slack adresi düzeltilene kadar her yeni aday kırmızı satır yazar. Kaçan kaydı dış sisteme almanın yolu, kaydı REST API ile tekrar okumaktır. Adres uzunluğu günlükte 300 karakterle kesilir; karşılaştırma yaparken adresin başına bakılır.

Dış sistem Ohana360'a veri yazacaksa ne kullanılır?

Ters yön REST API'dir: kullanıcı menüsü > API Anahtarları'ndan ohk_ ile başlayan bir anahtar üretilir ve her istek Authorization: Bearer başlığıyla gider. Boran Mobilya'nın muhasebe yazılımı faturayı kestiğinde Ohana360'taki fatura kaydını PATCH ile günceller; aynı ekran iki yönü de yönetir.

• Anahtar. Kapsam read yalnız GET yapar, readwrite yazar da. Anahtar üretildiği anda bir kez gösterilir, sonra yalnız öneki kalır; kullanıcı başına en çok 10 anahtar vardır ve anahtar kimin adına üretildiyse onun profil ve paylaşım izinleriyle çalışır. Org için API erişimi platform yöneticisi tarafından açılır; kapalıysa pencere bunu söyler.
• Uçlar. GET /api/objects/opportunity?stage=Closed%20Won listeler (varsayılan 200, en çok 500 kayıt), GET /api/objects/lead/00Q… tek kayıt döner, POST 201 ile yeni kayıt açar, PATCH günceller, DELETE kaydı Geri Dönüşüm Kutusu'na taşır. Doğrulama kuralı 422 ile durdurur, aday ve talepte atama kuralı sahibi atar.
• Döngü. API ile yazılan her kayıt eşleşen webhook'ları tetikler. Muhasebe faturayı güncellediğinde Ohana360 muhasebeye record.updated gönderir; dış sistem kendi yazdığı kaydı tanımazsa aynı kaydı tekrar yazar ve döngü başlar. Boran Mobilya'nın senaryosu, kendi gönderdiği PATCH'ten sonraki ilk paketi atlayarak bunu çözdü.
• Headless360. Marketplace'teki ücretsiz Sistem eklentisi, Kurulum'a API referans paneli ekler; webhook ekranı eklenti olmadan da çalışır.

Mağaza siparişleri için ayrı bir gelen uç vardır: POST /api/commerce/order, Bearer anahtarıyla sipariş numarasına göre kaydı açar ya da günceller; WooCommerce, Shopify ve ikas için hazır bağlayıcılar pazaryeri sipariş rehberinde. Satış tarafındaki kayıt yapısı Satış360 sayfasında.

Dahil değil: webhook'un yapmadıkları

• Yeniden deneme yoktur. Her olay bir kez gönderilir; 5 saniyede 2xx gelmezse kırmızı satır yazılır ve paket tekrar gönderilmez. Kuyruk, üstel bekleme ya da elle "tekrar gönder" düğmesi bulunmaz.
• Başarısız teslim bildirim üretmez. Zil, e-posta ya da push gitmez; günlük elle açılır. Webhook kendiliğinden pasife düşmez.
• Koşul Kurulum webhook'unda yoktur. Obje ve olay seçilir; alan koşulu için akış ve Webhook Çağır aksiyonu kullanılır.
• Paket değişen alanı ve eski değeri taşımaz. Kaydın son hali gider; fark almak dış sistemin işidir.
• Alan seçimi yoktur. Kaydın bütün alanları gönderilir; Maaş ya da özel notlar gibi alanlar pakette gizlenemez. Dış sistem o alanları görmemeliyse webhook o objeye kurulmaz.
• İstek başına 20 teslim. Tek seferlik büyük içe aktarmada 21. ve sonraki olaylar gönderilmez; toplu taşımada REST API kullanılır.
• Gövde ve cevap saklanmaz. Günlükte zaman, olay, obje, 300 karaktere kesilmiş adres ve HTTP kodu vardır; son 100 satır tutulur.
• Yönlendirme izlenmez. 301 ya da 302 dönen adres başarısız sayılır; hedef adres son haliyle yazılır.
• İç ağ adresi kabul edilmez. localhost, .local, .internal ve özel IP aralıkları reddedilir; dış sistem internetten erişilebilir olmalıdır.
• Zamanlanmış akışın alan güncellemesi olay üretmez. Sabah 09:00 taramasında değişen alan için record.updated gitmez; aynı akışa Webhook Çağır eklenirse paket gider.
• Paket içeriği özelleştirilemez. Alan eşleme, şablon ya da farklı biçim (XML, form) yoktur; dönüştürme Make, Zapier ya da kendi servisinizde yapılır.
• Örnek paket kısa olay adını gösterir. Yeni Webhook penceresindeki örnekte event, seçili olayın kısa adıyla (create, update, delete) yazar; gerçek paket record.created, record.updated ya da record.deleted gönderir. Dış sistemde uzun ad beklenir.

İlk webhook kurulurken neler kontrol edilir?

Beş dakikalık bir kontrol listesi, ilk kırmızı satırı ve ilk döngüyü önler. Boran Mobilya'nın listesi:

1. Adres https ile mi yazıldı? http adresi https'e yönlendiriyorsa teslim 301 ile düşer.
2. Test Gönder yeşil mi? Ping paketi 2xx almadan gerçek olaylar açılmaz.
3. İmza dış sisteme kaydedildi mi? Anahtar yenilendiyse iki taraf da güncel mi?
4. Olay seçimi dar mı? Yalnız kazanılan fırsat gerekiyorsa Kurulum webhook'u değil, koşullu akış ve Webhook Çağır.
5. Geri yazan sistem kendi yazdığını tanıyor mu? API ile dönen her yazım yeni bir olaydır.
6. Günlüğe kim bakacak? Başarısız teslim bildirim üretmediği için haftada bir Teslimatlar ve Otomasyonlar ve Entegrasyonlar sayacı kontrol edilir.