AI Çağrı Merkezi API Rehberi: Webhook ve REST API
Çağrı açıldı. Müşteri "geçen hafta verdiğim sipariş" diye başlıyor, ekranda ise boş bir profil duruyor. Temsilci — ya da yapay zeka ajanı — üç saniye içinde ya doğru bilgiyi görür ya da müşteriyi beklemeye alır. Beklemeye alınan çağrı çoğu zaman ikinci bir aramaya döner; ikinci arama da genelde daha sinirli bir müşteriyle gelir.
O boşluğu kapatan şey API. Aşağıda REST ile webhook'un işi nasıl bölüştüğünü, verinin bir çağrı boyunca hangi sırayla aktığını ve entegrasyonun en sık nerede çuvalladığını anlatıyorum. Süslemeden.
REST ve webhook: kim kime soruyor?
REST API sizin sorduğunuz yerdir. Sistem A, sistem B'ye HTTP üzerinden "bu müşterinin kaydını ver" der; B genelde JSON döner. Talep sizden çıkar.
Webhook tam tersidir. Kayıt değiştiğinde B, önceden verdiğiniz URL'ye kendisi istek atar. Sormazsınız, haber gelir.
Ayrım akademik değil, doğrudan operasyona yansıyor. Sipariş durumunu her on saniyede bir REST ile sorgularsanız günde binlerce boş sorgu üretirsiniz ve yine de on saniyelik gecikmeyle yaşarsınız. Webhook'ta gecikme yoktur; buna karşılık bildirim düşerse haberiniz de olmaz.
Çoğu ekip için başlangıçta webhook'suz REST yeter. Eş zamanlı çağrı sayısı artınca yetmez.
Bir çağrının veri akışı
Tipik bir gelen çağrıda sıra şöyle işler:
Numaradan kimliğe. Santral çağrıyı açar, arayan numarayı yakalar. Ajan REST ile CRM'e sorar: bu numara kime ait? Yanıt gelmezse konuşma "adınızı alabilir miyim" ile başlar. Felaket değil ama kişiselleştirme orada kaybedilir.
Bağlam yüklemesi. Açık sipariş, son destek kaydı, bakiye, yaklaşan randevu. Burada tek bir zengin endpoint, altı ayrı çağrıdan iyidir; her ek istek yanıt süresine birkaç yüz milisaniye ekler ve bu konuşmada duyulur.
Konuşma sırasındaki değişiklik. Müşteri anlatırken kargo teslim edilir ya da ödeme düşer. Ajanın bunu çağrı bittikten sonra değil, konuşurken bilmesi gerekir. Webhook'un asıl işi burasıdır.
Kapanış yazması. Çağrı biterken özet, etiket, sonuç kodu ve kayıt bağlantısı REST ile CRM'e yazılır. Bu adım atlanırsa ertesi gün arayan aynı müşteri her şeyi baştan anlatır.
Dört adımın üçü REST, biri webhook. Oran pratikte genelde böyle kalıyor. Hazır entegrasyon katmanı kullanıyorsanız bu sıralamanın çoğu sizin için kurulu gelir; kurmuyorsanız sırayı bu şekilde planlayın.
Webhook sessizce düşer
Webhook'un tehlikeli yanı, bozulduğunda gürültü çıkarmaması. REST isteği patlarsa loglarda 500 görürsünüz. Webhook gelmezse hiçbir şey görmezsiniz. Sistem çalışıyor gibi durur, veri eskir.
Sahada işe yarayan dört önlem:
İmza doğrulama. Webhook adresiniz internete açıktır. Gövdenin imzasını (genelde HMAC) doğrulamıyorsanız o adrese isteyen istediğini gönderir.
Idempotency. Kaynak sistem aynı olayı iki kez gönderebilir; yeniden deneme sırasında bu sık olur. Olay kimliğini saklayıp tekrarı yutmazsanız tek iptal iki kez işlenir.
Kuyruk, sonra iş mantığı. Gelen isteği doğrudan işlemeyin. Önce kuyruğa alıp hemen 200 dönün, işi arkada yapın. Yavaş yanıt veren endpoint'i kaynak sistem bir süre sonra beslemeyi bırakır.
Gecelik mutabakat. Günde bir kez son 24 saatin kayıtlarını REST ile çekip kendi tarafınızla karşılaştırın. Kaçan olay burada yakalanır.
Dördüncüsü sıkıcı bir iş. Sessiz veri kaybını bulan da genelde o oluyor.
Güvenlik ve KVKK tarafı
Çağrı verisi hassastır: ses kaydı, kimlik bilgisi, adres, bazen sağlık ya da finans detayı. Genel bilgilendirme düzeyinde, API katmanında bakılması gerekenler şunlar:
Kimlik doğrulamada OAuth 2.0 ya da kısa ömürlü token; kalıcı anahtarı koda gömmek yerine ortam değişkeni.
Her entegrasyona ayrı anahtar. Sızan anahtar tüm hattı değil, tek hattı kapatsın.
TLS zorunlu. Düz HTTP'ye bakan webhook adresi olmasın.
En az yetki ilkesi. Ajanın siparişi okuması gerekiyorsa silme yetkisi neden duruyor?
Log hijyeni. Hata ayıklamak için tam API yanıtını loglamak, kimlik numarasını üç ayrı sisteme kopyalamanın en kolay yoludur.
Yasal çerçeveyi ayrıntısıyla güvenlik ve KVKK tarafında ele aldık. Buradaki tek cümlelik özet şu: veriyi taşıdığınız her yeni bağlantı, korumanız gereken yeni bir yüzeydir.
En sık düşülen tuzaklar
Belirti | Gerçek sebep ve çözüm |
|---|---|
Ajan müşteriyi tanımıyor | Numara formatı. CRM'de 05321234567, santralden +905321234567 geliyor. Eşleştirmeden önce iki tarafı da tek biçime normalize edin. |
Staging'de çalıştı, canlıda timeout | Canlı CRM'de kayıt hacmi bambaşka; sorgu indekssiz bir alanda dönüyor. Test verisiyle ölçülen yanıt süresi yanıltır. |
Aynı sipariş iki kez iptal edildi | Idempotency yok. Yeniden deneme aynı olayı ikinci kez işledi. Olay kimliğini kaydedin. |
429 Too Many Requests | Rate limit. Her çağrıda altı endpoint gezmek yerine tek birleşik yanıt ve kısa ömürlü önbellek kullanın. |
Webhook geliyor ama alanlar boş | Sağlayıcı yalnızca kayıt kimliğini gönderiyor. Detay için REST ile geri sormanız gerekiyor; bu normaldir, dokümanda yazar. |
Kurumsal tarafta hikâye biraz değişir; SAP, Logo ya da Netsis gibi sistemlerin yanıt süreleri ve kimlik doğrulama modelleri farklı çalışır. Onu ayrıca ERP entegrasyonu yazısında anlattık.
Nereden başlamalı
Sırayı tersten kurmayın. Önce tek bir soru seçin — genelde en yüksek hacimli olan "siparişim nerede" oluyor — ve yalnızca o soruyu cevaplayacak REST bağlantısını kurun. Canlıda üç gün izleyin. Sonra webhook ekleyin.
AI Agent TR tarafında en çok gördüğümüz hata bunun tersi: ilk gün her sistemi bağlamaya çalışan ekipler, ikinci haftada hangi bağlantının bozulduğunu bulamadıkları için duruyor. Küçük başlayanlar aynı noktaya daha yavaş ama ayakta varıyor.
Hangi sistemlerin bağlanacağını ve çağrıların çoğunu hangi soruların kapladığını biliyorsanız, kurulumun kapsamı da bellidir. Demo talebi bırakın; mevcut CRM'iniz ve santralinizle bu akışın nasıl kurulacağını birlikte çıkaralım.
Sıkça Sorulan Sorular
REST ile mi webhook ile mi başlamalıyım?
REST ile. Çağrı açıldığında müşteriyi tanımak, anlık güncelleme almaktan daha temel bir ihtiyaç. Webhook'u, konuşma sırasında değişen veri sizi gerçekten yaktığında ekleyin.
Webhook'un geldiğini nasıl doğrularım?
Gelen her isteği olay kimliğiyle birlikte loglayın ve günlük bir mutabakat işi kurun. Sağlayıcı panelindeki teslim raporu da işe yarar, ama tek başına güvenmeyin; sizin tarafınızda 200 dönüp işlenmeden düşen istekler orada başarılı görünür.
API entegrasyonu ne kadar sürer?
Tek sistem ve tek senaryo ise birkaç gün. Çok sistemli, özel iş kuralı olan kurulumlar haftalara yayılır. Süreyi belirleyen genelde kod değil, karşı tarafın API dokümanının ne kadar güncel olduğu.
CRM'imizin açık API'si yoksa ne olur?
Birkaç yol kalır: veritabanı üzerinden okuma, zamanlanmış dosya aktarımı ya da araya bir ara katman koymak. Hepsi anlık veriden ödün verir. Böyle bir durumda beklentiyi baştan "çağrı sırasında güncel" değil, "sabah senkronu kadar güncel" diye kurmak daha dürüst olur.
