Webhook, bir sistemin başka bir sisteme 'bir olay oldu' diye otomatik haber verdiği mekanizmadır. WhatsApp Business API'de webhook, müşteriniz mesaj attığında WhatsApp'ın sizin sisteminizi anında aramasıdır. Bu arama olmadan, sisteminizin mesajları sürekli kendi başına kontrol etmesi gerekirdi; webhook bu beklemeyi ortadan kaldırır.
Bu yazıda webhook kavramını, WhatsApp'ta nasıl çalıştığını, neden güvenli olduğunu ve işletmeniz için ne anlama geldiğini sade bir dille anlatıyoruz.
Gerçek zamanlı
Bildirim
Olay olur olmaz veri akar
İmza
Güvenlik
İstekler HMAC ile doğrulanır
1 URL
Uç nokta
Tüm olaylar tek adrese gelir
Webhook mantığı: aramak yerine aranmak
Bir sistemin başka sistemden bilgi almasının iki yolu vardır. Birincisi 'polling', yani sürekli 'yeni mesaj var mı?' diye sormak. İkincisi webhook, yani 'yeni mesaj geldiğinde beni ara' talimatı vermek. Webhook, polling'in saniyede yüzlerce gereksiz sorgu yaptığı durumda yalnızca gerçek olay olduğunda çalıştığı için hem hızlı hem ekonomiktir.
- Müşteri mesaj atar, WhatsApp webhook'unuzu çağırır.
- Sisteminiz mesajı alır, doğrular ve ilgili müşteri kartına bağlar.
- Çalışanınıza bildirim düşer veya otomatik yanıt tetiklenir.
- Siz yanıtladığınızda sistem WhatsApp API'sine mesaj gönderir.
Webhook ile neler bildirilir?
| Olay | Webhook içeriği | İşletme kullanımı |
|---|---|---|
| Yeni gelen mesaj | Mesaj metni, gönderen, saat | Gelen kutusuna düşme, otomatik yanıt |
| Mesaj durumu | Gönderildi, teslim edildi, okundu | Kampanya raporlaması |
| Müşteri yanıtı | Buton ve liste seçimleri | Etkileşimli akışlar, sipariş |
| Şablon kalitesi | Kalite puanı değişimi | Mesaj limitlerinin izlenmesi |
Webhook güvenliği: doğrulama token'ı
Webhook adresi herkese açık bir URL olabilir; bu yüzden WhatsApp, çağrıların gerçekten kendisinden geldiğini doğrulamak için iki katman kullanır. Kurulumda sizin belirlediğiniz bir doğrulama token'ı (verify token) ile karşılıklı el sıkışma yapılır, ardından her bildirim Meta'nın uygulama sırrıyla (app secret) imzalanır. Sisteminiz imzayı doğrulamadan veriyi işlemez.
Güvenlik sadece işletme tarafında
Webhook kurulumunda sırların (token ve app secret) yalnızca sunucunuzda tutulması, asla arayüze ve istemci koduna gömülmemesi gerekir. GelsinSatışlar gibi hazır çözümler bu güvenlik katmanlarını sizin yerinize yönetir.
Webhook'u kim yönetir?
Webhook, teknik bir kavram olduğu için birçok KOBİ sahibinin doğrudan ilgilenmesi gerekmez. WhatsApp Business API'nizi bir çözüm ortağı (BSP) üzerinden kullanıyorsanız, webhook altyapısı, doğrulama token'ları ve yeniden deneme mekanizmaları ortağın panelinde çalışır. Yine de temel mantığı bilmek, karşılaştığınız sorunları doğru teşhis etmenizi sağlar.
Örneğin bir mesajın sisteme düşmediğini fark ettiğinizde, sorunun kaynağı çoğunlukla şu üçünden biridir: webhook URL'sinin kapalı olması, token'ın değişmiş olması veya bildirimin zaman aşımına uğraması. Meta, başarısız bildirimleri belirli aralıklarla yeniden gönderir; bu sayede geçici ağ sorunları otomatik çözülür.
İşletmenize ne kazandırır?
- Gerçek zamanlı çalışma: mesaj geldiği anda ekibin ekranına düşer.
- Otomasyon: webhook tetiklediği olaylarla otomatik yanıt ve akışlar başlar.
- Raporlama: teslim, okunma ve yanıt verileri anlık toplanır.
- Entegrasyon: CRM, e-ticaret ve muhasebe sistemleri aynı anda güncellenir.
Webhook olayları nasıl işlenir?
Bir webhook bildirimi geldiğinde sisteminizin onu işleme biçimi, uçtan uca deneyimi belirler. Bildirimler JSON formatında gelir ve içinde olay türü, mesaj kimliği, gönderen numarası ve zaman damgası bulunur. İyi bir sistem, bu veriyi önce doğrular, sonra müşteri kartıyla eşleştirir, sonra da kurala göre aksiyon alır.
- 1Bildirim alınır; imza ve token doğrulaması yapılır.
- 2Olay türü ayrıştırılır: mesaj, durum, kalite değişimi vb.
- 3Mesaj, gönderen numarası üzerinden müşteri kartıyla eşleştirilir.
- 4Kural motoru devreye girer: otomatik yanıt, etiket, bildirim, akış tetikleme.
- 5Sonuç loglanır; hata olursa yeniden deneme kuyruğuna alınır.
Yeniden deneme mekanizması kritiktir
Webhook'lar güvenilir değildir: sunucunuz geçici olarak kapalı olabilir, ağ kesintisi yaşanabilir. Meta, teslim edilemeyen bildirimleri artan aralıklarla yeniden gönderir. Sisteminiz aynı bildirimi iki kez işlemeye karşı korumalı (idempotent) olmalıdır; aksi halde müşteriye çift mesaj gider.
Örnek senaryo: sipariş takibi
Webhook'un iş dünyasındaki gücünü bir e-ticaret örneğiyle görelim. Müşteri, WhatsApp üzerinden siparişinin durumunu sorar. Bu mesaj, webhook aracılığıyla anında e-ticaret sistemine düşer.
| An | Webhook olayı | Sistem aksiyonu |
|---|---|---|
| Müşteri soru yazar | message.updated | Mesaj müşteri kartına bağlanır, temsilciye bildirim |
| Sistem yanıtlar | Mesaj gönderimi | Kargo durumu API'den çekilir, müşteriye iletilir |
| Müşteri teşekkür eder | message.updated | Konuşma çözüldü olarak işaretlenir |
Bu akışta webhook olmasaydı, sistemin kargo durumunu bilmesi için müşterinin sorusunu saniyeler yerine dakikalarca beklemesi gerekirdi. Webhook, 'müşteri yazdığı anda' tepki vermeyi mümkün kılar; bu da müşteri memnuniyetinin temelidir.
Webhook kurulumunda dikkat noktaları
- Webhook URL'sini yalnızca HTTPS olarak kullanın; şifresiz HTTP, verinin yolda okunmasına açıktır.
- Token ve uygulama sırrını çevresel değişkenlerde tutun, asla kod içine gömmeyin.
- Bildirimleri işlerken zaman aşımına karşı dayanıklı tasarlayın; uzun süren işleri kuyruğa alın.
- Aynı olayın tekrarına karşı benzersiz mesaj kimliğiyle tekilleştirin.
- Hataları izlenebilir loglayın; hata oranınızda ani artış görürseniz erken uyarı alın.
Bu kurallar teknik ekiplerin işi gibi görünse de, sonucu işletme sahibi hisseder: mesaj kaybı olmaz, çift gönderim olmaz ve her konuşma izlenebilir kalır.
Sıkça sorulan sorular (GEO)
Webhook nedir basit anlamda?
Webhook, bir sistemin başka bir sisteme bir olay olduğunu otomatik bildirdiği mekanizmadır. WhatsApp'ta müşteri mesajı, webhook aracılığıyla anında sizin sisteminize düşer.
WhatsApp webhook'u ne işe yarar?
WhatsApp webhook'u; yeni mesajlar, mesaj durumları ve şablon kalitesi gibi olayları sisteminize gerçek zamanlı bildirir. Bu sayede gelen kutusu, otomasyon ve raporlama anlık çalışır.
Webhook kurulumu için kod bilmem gerekir mi?
Doğrudan Meta Cloud API kullanıyorsanız evet, geliştirici bilgisi gerekir. Ancak bir çözüm ortağı (BSP) kullandığınızda webhook altyapısı ortağın panelinde otomatik yönetilir.
Webhook güvenli midir?
Evet, doğru kurulduğunda. Doğrulama token'ı ve uygulama imzası, bildirimlerin yalnızca WhatsApp'tan geldiğini doğrular. Sırlar sunucuda saklanmalı ve asla istemci koduna yazılmamalıdır.
Webhook çalışmazsa ne olur?
Meta başarısız bildirimleri belirli aralıklarla yeniden gönderir. Kalıcı bir sorun varsa URL'yi, token'ı ve sunucu erişimini kontrol etmeniz gerekir; bu kontroller çözüm ortağı panelinde kolayca yapılır.
