Your AI Connector Docs

Webhook’lar

Web kancaları (webhooks), önemli bir şey olduğunda — yeni bir kişi oluşturulduğunda, bir randevu alındığında veya bir mesaj geldiğinde — Your AI Connector'ın diğer iş araçlarınızı otomatik olarak bilgilendirmesini sağlar. Güncellemeleri manuel olarak kontrol etmek yerine, bağlı sistemleriniz bir şey olduğu anda anında bildirim alır.


Webhook Nedir?

Bir web kancasını iki uygulama arasında otomatik bir kısa mesaj gibi düşünün. Your AI Connector içinde bir şey olduğunda (yeni bir kişinin kaydolması gibi), platform seçtiğiniz başka bir sisteme anında bildirim gönderir. Bu bildirimlerin gönderilmesi gereken bir web adresi (bir “web kancası URL’si”) sağlarsınız; bu genellikle CRM’niz, otomasyon platformunuz veya geliştiriciniz tarafından sağlanır.

Web kancaları (Webhooks) sayfası yalnızca Your AI Connector dışına veri gönderir. Burada ayarlanan web kancaları tek yönlüdür; Your AI Connector kaynağından diğer araçlarınıza veri aktarır. Yeni bir potansiyel müşteri veya başka bir veriyi içeri (bir web sitesi formundan, CRM’inizden veya GoHighLevel’dan) almak için iki seçeneğiniz vardır. Web kancası tetikleyicisine sahip bir Otomasyon, formunuzun veya aracınızın veri gönderebileceği bir web adresi sağlar ve bu otomasyonun adımları daha sonra kişiyi oluşturabilir, mesaj gönderebilir ve daha fazlasını yapabilir. Alternatif olarak sisteminiz, API anahtarınızı kullanarak örneğin Kişi Oluştur işlemi gibi bir API çağrısı yapabilir; API Erişimi ve Huniler bölümlerine bakın.

Web kancaları yalnızca bazı planlarda mevcuttur. Planınız web kancalarını içermiyorsa, Web kancaları sayfası kullanılamaz ve hiçbir etkinlik gönderilmez. Daha önce kaydettiğiniz her şey hesabınızda kalır ve web kancalarını içeren bir plana geçtiğiniz anda tekrar gönderilmeye başlar. Planınızın özellikleri faturalandırma sayfanızda listelenmiştir ve sağlayıcınız hangi plana geçmeniz gerektiği konusunda size bilgi verebilir.

Not: Web kancalarını ayarlamak bazı teknik yapılandırmalar gerektirir. Bu konuda kendinizi rahat hissetmiyorsanız, bu sayfayı geliştiricinizle paylaşın veya kodlama gerektirmeden web kancası URL’leri sağlayan Zapier, Make veya Pabbly gibi bir otomasyon platformu kullanın.

Yaygın kullanım alanları şunlardır:

  • Yeni kişileri CRM’nizle senkronize etmek.
  • Bir etiket uygulandığında Zapier, Make veya Pabbly’de bir iş akışını tetiklemek.
  • Bir insan uyarıldığında Slack’te ekibinizi bilgilendirmek.
  • Bir randevu alındığında takvim sisteminizi güncellemek.
  • Konuşma özetlerini veritabanınıza kaydetmek.

Webhook’ları Ayarlama

  1. Sol kenar çubuğunda Ayarlar’a (dişli simgesi) tıklayın.
  2. Ayarlar kenar çubuğunda, Entegrasyonlar grubu altında Web kancaları’na tıklayın.

Henüz hiçbir webhook yapılandırılmamış bir hesapta sayfa şu şekilde görünür:

  1. Sağ üst köşedeki New webhook (Yeni webhook) düğmesine tıklayın. Sayfa içinde bir form açılacaktır:
  1. Şunları doldurun:
    • Uç Nokta URL’si (Endpoint URL) — Your AI Connector'ın etkinlik bildirimlerini göndereceği web adresi. Bunu harici sisteminizden (CRM, otomasyon platformu veya özel sunucu) alırsınız.
    • Ad — daha sonra tanıyacağınız bir etiket (örneğin “Slack uyarıları” veya “CRM senkronizasyonu”). Yalnızca referansınız içindir.

Webhook URL’niz herkese açık, erişilebilir bir https:// adresi olmalıdır. Düz http:// adresleri, localhost veya özel ağ adresleri ve platform içi adresler kaydettiğinizde reddedilir. Kendi makinenizden test etmek için localhost yerine herkese açık bir tünel (webhook.site veya ngrok) kullanın.

  1. Etkinlikler altında, bu webhook’un almasını istediğiniz etkinlikleri tıklayın — 24’ünün tamamı 24 Webhook Etkinliği bölümünde listelenmiştir.
  2. (İsteğe bağlı) Your AI Connector'ın geçici bir hata durumunda tekrar denemesini istiyorsanız Başarısız teslimatları yeniden dene seçeneğini açın — bkz. Başarısız Teslimatları Yeniden Deneme.
  3. Webhook oluştur’a tıklayın. Formun altındaki listede görünecektir ve uç noktanıza örnek bir yük (payload) göndermek için istediğiniz zaman satırındaki Test düğmesine tıklayabilirsiniz.

İzin gerekli. Webhook eklemek, düzenlemek veya test etmek, Entegrasyonlar “düzenleme” izni gerektirir (yalnızca görüntüleme yetkisi olan ekip üyeleri form yerine salt okunur bir bildirim görür).

Bir webhook’u imzalamak için önce kaydedilmiş olması gerekir — düzenlemek için mevcut bir webhook satırını açın; düzenleme formunun altında İmzalama gizli anahtarı paneli görünecektir. Henüz kaydedilmemiş yeni bir taslağın henüz imzalama seçeneği yoktur — bkz. aşağıdaki İmzalı Yükler.


Tüm Müşteri Hesaplarınız İçin Tek Bir Webhook (Ajanslar)

Bir ajans yönetiyorsanız, aynı webhook’u her müşteri hesabında yeniden oluşturmanız gerekmez. Ajans hesabında, webhook formunda fazladan bir geçiş düğmesi bulunur: Tüm müşteri hesapları için de tetikle. Bunu açtığınızda, bu webhook ajansınızın altındaki her müşteri hesabında gerçekleşen etkinlikleri de alır — tek bir uç nokta, tüm ajans.

Nasıl çalışır:

  • user bloğu, bir etkinliğin hangi müşteriye ait olduğunu size bildirir. Her bildirim, etkinliğin gerçekleştiği hesabı tanımlayan bir user bloğu içerir, böylece otomasyonunuz müşteri bazında yönlendirme yapabilir.
  • Webhook’unuzun kendi ayarları her yerde geçerlidir. Seçtiğiniz etkinlikler, imzalama gizli anahtarı ve yeniden deneme ayarı, müşteri hesabı teslimatları için de kullanılır.
  • Çift teslimat olmaz. Bir müşteri hesabının aynı URL’yi işaret eden kendi webhook’u varsa, o hesabın etkinlikleri için o webhook kullanılır; aynı etkinlik bir uç noktaya asla iki kez gelmez.
  • Müşteriler bunu görmez. Webhook, müşteri hesabının kendi Webhook’lar sayfasında görünmez ve müşteriler bunu kapatamaz; yönetimi size aittir.
  • Güvenilirlik müşteri hesabı bazında izlenir. Uç noktanız hata vermeye devam ederse, teslimatları başarısız olan hesap için otomatik olarak kapatılır (bkz. Webhook Güvenilirliği), tüm ajans için aynı anda kapatılmaz.

Geçiş düğmesi yalnızca ajans hesaplarında görünür. Bunu API üzerinden ayarlamak da desteklenir — bkz. Webhooks API içindeki apply_to_sub_accounts alanı.


Mevcut Tetikleyici Etkinlikler

24 webhook etkinliğinin her birini bağımsız olarak etkinleştirebilir veya devre dışı bırakabilirsiniz. Bir etkinlik tetiklendiğinde, Your AI Connector ilgili verilerle birlikte webhook URL’nize bir bildirim gönderir. Her etkinlik, ne anlama geldiği ve yük içinde yerleştirdiği event kodu, bu sayfanın alt kısmındaki 24 Webhook Etkinliği bölümünde birlikte listelenmiştir.

Bilmenizde fayda var: Görev Oluşturuldu, Görev Güncellendi ve Görev Tamamlandı seçenekleri tamamen seçilebilir durumdadır ve doğru şekilde kaydedilir. Günlük Özet Oluşturuldu da yakın zamanda eklenmiştir. Bu yükün yapısı için aşağıdaki Görev Tamamlandı Web Kancası bölümüne bakın.


Etiket Tabanlı Webhook Tetikleyicileri

subscribed_to_tags, bir web kancasının olaylarını bir etiketle sınırlandırmaz. Yalnızca hangi etiketlerin konuşma özeti bildirimi üreteceğini daraltır. Belirli bir etiket uygulandığında istek almak için, temsilci düzenleyicinin Etiketler sekmesindeki o etikete bir web kancası URL’si ayarlayın.

Web kancası formunun kendisinde, yeni bir web kancası oluştururken veya mevcut olanı düzenlerken etiket seçici bulunmaz; bu nedenle subscribed_to_tags yalnızca Web Kancaları API aracılığıyla veya destek ekibine danışılarak okunabilir ya da değiştirilebilir.

Bilmenizde fayda var: subscribed_to_tags listesine sahip mevcut bir web kancasını düzenlemek (yeniden adlandırmak, etkinliklerini değiştirmek, yeniden denemeleri açıp kapatmak), artık bu listeyi temizlemez; formda geri gönderilecek bir etiket seçici bulunmadığından, bu sayfadan kaydetme işlemi mevcut listeyi olduğu gibi bırakır. (Bu, 21 Temmuz 2026 öncesinde gerçek bir hataydı: web kancası formundan kaydetme işlemi, her zaman boş bir etiket listesi gönderdiği için listeyi silerdi. Eğer bir web kancası bu tarihten önce subscribed_to_tags listesini kaybettiyse, API aracılığıyla yeniden yapılandırılması gerekecektir.)

Etiketli Kişiler İçin Özet Oluştur

Bir web kancasının subscribed_to_tags listesi olduğu durumlarda, Özet Oluştur seçeneğini açabilirsiniz. Etkinleştirildiğinde, Your AI Connector bu etiketlerden biri uygulandığında kişi için otomatik olarak bir konuşma özeti oluşturur ve bunu web kancası verilerine dahil eder — ayrı bir istekte bulunmaya gerek kalmadan tam bağlam sunar.


Webhook’unuzu Test Etme

  1. Ayarlar → Entegrasyonlar → Webhook’lar yolunu izleyin.
  2. Webhook’unuzun satırında Test Et düğmesine tıklayın.
  3. Test verilerini alıp almadığını doğrulamak için harici sisteminizi kontrol edin.
  4. Sisteminizin verileri doğru şekilde ayrıştırabildiğinden emin olmak için veri biçimini gözden geçirin.

Tam bir uçtan uca test için, yapılandırılmış etkinliklerinizden birini tetikleyecek bir mesaj gönderin (bir yayın veya bağlı bir kanala gelen mesaj) ve webhook’un gerçek verilerle tetiklendiğini doğrulayın.

İpucu: Üretim sisteminizi bağlamadan önce ham web kancası verilerini incelemek için geliştirme sırasında webhook.site veya RequestBin gibi bir araç kullanın.

Başarılı Bir Teslimat Nedir

Test düğmesine tıkladığınızda veya olay gerçekten tetiklendiğinde aynı şeyi göndeririz:

  • POST isteği (asla GET değil), gövdesi JSON formatında ve Content-Type: application/json içerir.
  • İmzalı Yükler altında listelenen başlıklar. İmza başlıkları yalnızca bir imzalama gizli anahtarı belirlediğinizde dahil edilir.

Teslimatı şu durumlarda başarılı kabul ederiz:

  • Uç noktanız herhangi bir 2xx durumu ile yanıt verirse (200, 201, 204 — hepsi uygundur).
  • 30 saniye içinde yanıt verirse.

İnsanları şaşırtan birkaç şey:

  • Yanıt gövdesi yoksayılır. Herhangi bir özel JSON döndürmeniz gerekmez. Boş bir 200 yeterlidir.
  • Yönlendirmeler başarısızlık olarak sayılır. Bunları takip etmiyoruz, bu nedenle 301 veya 302 (sondaki eğik çizgi yönlendirmesi veya http’den https’ye yönlendirme dahil) başarısız bir teslimat olarak kaydedilir. Yönlendiren değil, nihai URL’yi kaydedin.
  • Sorgu dizeleri tam olarak desteklenir. https://your-app.com/hook?token=abc123 tam olarak kaydettiğiniz şekilde gönderilir, bu nedenle sorgu dizesine bir belirteç koymak, yola koymak kadar iyi çalışır.
  • URL’niz https:// olmalı ve herkese açık olarak erişilebilir olmalıdır. Your AI Connector'ün kendi altyapısına ait adresler reddedilir, ancak Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting veya başka herhangi bir yerdeki kendi uç noktalarınız sorunsuzdur.
  • Uç noktanızın önündeki bir güvenlik duvarı veya bot koruma katmanı bizi engelleyebilir. En yaygın durum Cloudflare’dir: Bölgenizde Bot Fight Mode veya yönetilen bir sınama açıksa, isteğimiz sunucunuza ulaşmak yerine 403 ile bir “Just a moment…” sınama sayfası alır — ve sunucudan sunucuya bir istek asla bir tarayıcı sınamasını geçemez, bu nedenle hem Test düğmesi hem de gerçek olaylar aynı şekilde başarısız olur. Test düğmesi, bu durum gerçekleştiğinde size bildirecektir (“Cloudflare isteğimize bir bot sınaması gösteriyor”). Bunu Cloudflare’de, webhook yolunuz (veya Webhook-Delivery/1.0 kullanıcı aracısı) için sınamaları atlayan bir Güvenlik / WAF kuralı ile düzeltin, ardından Test düğmesine tekrar tıklayın.
  • Güvenlik duvarınız bunun yerine bir IP izin listesine ihtiyaç duyuyorsa (örneğin, basit Bot Fight Mode’un bir WAF kuralı tarafından atlanamadığı, ancak İzin Ver olarak ayarlanmış bir IP Erişim Kuralının ondan önce çalıştığı Cloudflare’in ücretsiz planı), yardımcı olabiliriz: Test düğmesinden veya canlı bir olaydan gelen her teslimat, sabit bir IPv4 adresinden gönderilir (aralıklar yok, IPv6 yok, döndürme yok). Destek ekibiyle iletişime geçin, size izin listesine eklenecek adresi verelim. İmza doğrulamasını gerçek güven denetiminiz olarak tutun, çünkü nereden gelirse gelsin her yükü doğrular.
  • Test sonucu, uç noktanızın tam olarak ne yanıt verdiğini size söyler. Başarısız bir test artık genel bir hata yerine gerçek nedeni (uç noktanızın döndürdüğü HTTP durumu, bir zaman aşımı veya adrese hiç ulaşamadığımız) gösterir ve kaydedilmiş bir webhook üzerindeki test, imzalama açıkken tıpkı canlı bir olay gibi imzalı olarak gönderilir.

n8n, Make veya Zapier Kullanımı (“Test URL” ve “Production URL” karşılaştırması)

Otomasyon platformları genellikle size iki farklı webhook adresi verir ve bu durum insanların kafasını karıştırır:

  • Bir Test URL’si (n8n’de /webhook-test/ içerir). Bu URL, yalnızca tuvali aktif olarak izlediğinizde ve Listen for test event (veya Test workflow) düğmesine tıkladığınızda veri alır. Tek bir etkinliği yakalar ve ardından dinlemeyi durdurur; bu nedenle Your AI Connector içinde arka arkaya birkaç kez Test Et düğmesine tıklamak yalnızca ilkini yakalar ve bu da yalnızca dinleme penceresi o anda aktifse gerçekleşir. Test etmek için: önce n8n’de Listen for test event düğmesine tıklayın, ardından Your AI Connector'e geri dönün ve bir kez Test Et düğmesine tıklayın.
  • Bir Üretim URL’si (n8n’de /webhook/ içerir, -test içermez). Canlı etkinlikler için Your AI Connector içine yapıştırılacak olan budur. Yalnızca iş akışınız Aktif duruma getirildiğinde çalışır. İş akışı aktif değilse, Your AI Connector verileri doğru şekilde göndermiş olsa bile n8n isteği “404 / webhook not registered” hatasıyla reddeder.

Özetle: dinleme yaparken Test URL’si ile test edin, ancak webhook’un gerçek kişiler üzerinde çalışmaya devam etmesi için Production URL’sini Your AI Connector içine kaydedin ve iş akışının Active olduğundan emin olun.


Webhook Veri Formatı

Bir web kancası tetiklendiğinde, Your AI Connector web kancası URL’nize yapılandırılmış veriler (JSON) gönderir. Zapier veya Make gibi bir otomasyon platformu kullanıyorsanız, bu verileri sizin için otomatik olarak ayrıştırır. Özel bir entegrasyon oluşturuyorsanız:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}
Alan Açıklama
event Bildirimi tetikleyen tam etkinlik dizesi (örneğin, contactCreated, booked). Bu, etkinlik listesinde gösterilen görünen etiket değildir; her etiket ve eşleşen kodu 24 Webhook Etkinliği bölümündedir.
contact Etkinliğin ilgili olduğu kişi veya bir kişiyle bağlantılı olmayan etkinlikler (örneğin creditsRecharged) için null.
campaign Kişinin ait olduğu klasik kampanya veya yoksa null. Bir temsilci tarafından yönetilen kişiler buraya null ile gelir.
agent Görüşmeyi yöneten temsilci veya yoksa null.
user Verilerin sahibi olan hesap için temel kimlik bilgileri.

agent öğesini okuyun, campaign öğesini değil. Kampanyalar, Yapay Zeka Temsilcilerine ve Yayınlara taşındı (bkz. Kampanyalar Taşındı), bu nedenle kişileriniz bir temsilciyle birlikte bulunur ve agent size konuşmayı hangisinin yönettiğini söyler. campaign alanı, eski alıcıların çalışmaya devam etmesi için hala gönderilmektedir ancak genellikle null değerindedir; yalnızca hala klasik bir kampanyaya bağlantı taşıyan bir kişi için doldurulur. campaign değerinin her zaman orada olduğunu varsaymayın.

agent bloğu 15 Ağustos 2026 tarihinde geldi. Bu blok, bir konuşmaya bağlı olaylar olan campaign (sonlandırılmış sohbet, rahatsız etme, devam etme, arşivden çıkarma, yapay zeka duraklatma, yeni mesaj, konuşma özeti ve bir etiket üzerinde ayarlayabileceğiniz webhook) ile birlikte yer alır ve işlem yapan temsilcinin id ve name bilgilerini veya temsilci dahil olmadığında null değerini taşır. Tamamen ek niteliğindedir: halihazırda aldığınız her alan değişmeden kalır, bu nedenle o tarihten önce oluşturduğunuz bir alıcı, güncellenmesi gereken hiçbir şey olmadan çalışmaya devam eder.

Bazı etkinlikler kendi ekstra üst düzey bloklarını ekler. Örneğin, Randevu Alındı, Randevu İptal Edildi ve Randevu Yeniden Planlandı bir appointment bloğu ekler (bkz. Randevu Alındı Webhook’u), Yeni Mesaj metni içeren tam bir message bloğu ekler (bkz. Yeni Mesaj Webhook’u) ve Teslimatlar ile Okundu bilgileri, yalnızca mesajın kimliğini ve durumunu içeren kısa bir message bloğu ekler (bkz. Teslimatlar ve Okundu Webhook’u).

Teslimatlar ve Okundu Bilgileri size hangi mesajın olduğunu söyler, ancak ne dediğini söylemez. Bunlar, mesajın id ve status değerlerini içeren bir message bloğu taşır — ve bu id, mesaj gönderme uç noktasının geri döndürdüğü messageId ile aynıdır, böylece bir teslimat veya okundu bilgisini gönderdiğiniz tam mesajla eşleştirebilirsiniz — ancak mesaj gövdesi içermez. Yanıtlar ise hiçbir message bloğu taşımaz. Gönderilen veya alınan kelimelere ihtiyacınız varsa, bunlarla birlikte Yeni Mesaj etkinliğine abone olun.

Alıcınızı yazmadan önce bilmeniz gereken iki şey. timestamp alanı yoktur ve data sarmalayıcısı bulunmaz. Yukarıda gösterildiği gibi, her blok JSON nesnesinin en üst düzeyinde yer alır.

24 Webhook Etkinliği

Uygulamada işaretlediğiniz görünen etiket ve yük içinde gönderilen event kodu ile 24 webhook etkinliği. event kodu, görünen etiketle eşleşmeyen kısa bir dizedir, bu nedenle alıcınızı etikete göre değil, koda göre eşleştirin:

Görünen etiket (uygulamada) Yükteki event kodu Ne anlama gelir
Kişi Oluşturuldu contactCreated Hesabınıza yeni bir kişi eklendi (manuel olarak, içe aktarma yoluyla veya API aracılığıyla).
Kişi Duraklatıldı contact_paused Bir kişi görüşmesi duraklatıldı (bot yanıt vermeyi durdurur).
Kişi Devam Ettirildi contact_resumed Duraklatılmış bir kişi görüşmesi devam ettirildi.
Kişi Rahatsız Etmeyin contact_do_not_disturb_changed Bir kişinin Rahatsız Etmeyin ayarı açıldı.
Kişi Arşivden Çıkarıldı contact_unarchived Arşivlenmiş bir kişi yeni bir mesaj göndererek onu tekrar aktif gelen kutunuza getirir.
Yeni Mesaj new_message Herhangi bir kanaldaki bir görüşmeye herhangi bir mesaj eklendi — hem kişinin size gönderdiği mesajlar hem de yapay zekanızın veya ekibinizin onlara gönderdiği mesajlar. Gerçek mesaj metnini taşıyan tek etkinlik budur (bkz. Yeni Mesaj Webhook’u).
Yanıtlar replied Bir kişi bir mesaja yanıt verdi.
Okundu read Bir kişi bir mesajı okudu (okundu bilgisini destekleyen kanallarda). Okunan mesajın kimliğini taşır — bkz. Teslimatlar ve Okundu Webhook’u.
Teslimatlar delivered veya undelivered Bir mesaj bir kişiye başarıyla teslim edildi (teslimat başarısız olduğunda undelivered). Mesajın kimliğini taşır — bkz. Teslimatlar ve Okundu Webhook’u.
İnsan Uyarısı humanAlerted Yapay zeka botu bir görüşmeyi yönetemeyeceğine karar verir ve insan müdahalesi için işaretler.
Sohbet Sonlandırıldı chat_concluded Yapay zeka botu bir görüşmenin sona erdiğine karar verir (rezervasyon yapıldı, potansiyel müşteri elendi vb.).
Randevu Alındı booked Bir kişi rezervasyon sistemi üzerinden randevu alır.
Randevu İptal Edildi appointment_cancelled Bir randevu iptal edildi: sohbette yapay zeka tarafından, uygulamada sizin tarafınızdan, API aracılığıyla veya bağlı Google Takvim’de. Randevu Alındı ile aynı gövde, appointment.cancelation_reason ile birlikte. Bkz. Randevu İptal Edildi ve Yeniden Planlandı Webhook’ları.
Randevu Yeniden Planlandı appointment_rescheduled Bir randevu, aynı yerlerin herhangi birinden yeni bir zamana taşınır. Randevu Alındı ile aynı gövde artı eski başlangıç ve bitiş zamanlarını içeren bir previous bloğu.
Kredi Harcandı creditsSpent Hesabınızdan kredi düşüldü.
Kredi Yüklendi creditsRecharged Otomatik yükleme veya manuel satın alma yoluyla hesabınıza kredi eklendi.
Düşük Kredi Bakiyesi Test teslimatında lowCreditBalance, gerçek bir teslimatta Low Credit Balance Kredi bakiyenizin uyarı eşiğinizin (kendi eşiğinizi belirlemediyseniz 100 kredi) altına düştüğüne dair erken bir uyarı. Alt hesaplarının tümü tek bir havuzdan harcama yapan ajanslar için tasarlanmıştır. Kişi bloğu yerine balance, threshold ve account_email taşır, bakiye düşük kaldığı sürece en fazla 24 saatte bir gönderilir ve bakiye eşiğin üzerine çıkar çıkmaz tekrar devreye girer.
Görev Oluşturuldu taskCreated Bir görev oluşturuldu.
Görev Güncellendi taskUpdated Bir görev, tamamlama aşamasına geçmeden değişti.
Görev Tamamlandı taskCompleted Bir görev, tamamlama aşaması olarak yapılandırılmış bir aşamaya geçti.
Günlük Özet Oluşturuldu dailySummaryCreated Günlük özet raporunuz oluşturuldu.
Kanal Bağlandı channelConnected Henüz gönderilmiyor — seçilebilir ancak bugün hiçbir şey bunu yaymıyor. Bunun üzerine geliştirme yapmayın. Bir mesajlaşma kanalı bağlanmayı tamamladığında kullanılmak üzere tasarlanmıştır.
Yayın Başladı broadcastStarted Bir yayın gönderilmeye başlar (durumu Gönderiliyor olarak değişir). Başlangıç başına bir kez tetiklenir, duraklatılmış bir yayın devam ettirildiğinde de dahil. Kişi bloğu yerine bir broadcast bloğu taşır: id, ad, kanal, durum, önceki durum, hedeflediği liste (list_id, list_name, is_smart_list), scheduled_at, total_contacts.
Yayın Tamamlandı broadcastCompleted Bir yayın biter (durumu Gönderildi veya Başarısız olarak değişir). Aynı broadcast bloğu artı completed_at ve mevcut olduğunda completion_summary (total_sent, permanently_failed, unique_replied, failure_rate, had_errors). Bir Akıllı Yayın Listesini harici araçlara bağlamak için bu ikisini kullanın.

Bu listede asla görünmeyen iki kod daha vardır çünkü bunlara abone olamazsınız: tek bir etikete ayarlanan bir web kancası URL’si tarafından gönderilen contact_tags_updated ve bir web kancasının subscribed_to_tags listesindeki bir etiket için sohbet özeti yazıldığında gönderilen summary_generated. |

Kanal Bağlandı henüz gönderilmiyor. Etkinlik listesinde görünür ancak şu an hiçbir şey bunu tetiklemez. Buna göre geliştirme yapmayın.

Etiket tabanlı ve görev bildirimleri kendi ayrı şekillerini kullanır. Bkz. Kişi Etiketleri Güncellendi ve Görev Tamamlandı.


Kişi Oluşturuldu Webhook’u

Kişi Oluşturuldu etkinliği tetiklendiğinde gönderilir (yeni bir kişi manuel olarak, içe aktarma yoluyla veya API aracılığıyla eklendiğinde).

Olay adı

contactCreated

Yük formatı

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}
Alan Açıklama
event Bu etkinlik için her zaman contactCreated değerindedir.
contact.id Yeni kişinin benzersiz kimliği.
contact.email / contact.phone_number Biliniyorsa kişinin e-postası ve telefonu (kanala bağlı olarak her ikisi de boş olabilir).
contact.first_name / contact.last_name Biliniyorsa kişinin adı.
contact.human_alerted / contact.human_alert_reason Kişinin insan müdahalesi için işaretlenip işaretlenmediği ve nedeni.
contact.is_bot_active Yapay zeka botunun bu kişi üzerinde şu anda aktif olup olmadığı.
contact.ad_referral Kişinin geldiği Meta reklamı (Click-to-WhatsApp, Click-to-Instagram veya Click-to-Messenger) ya da null. Bkz. Click-to-WhatsApp Reklam İlişkilendirmesi.
contact.ad_attribution Bu kişinin eşleştirildiği web sitenizdeki reklam tıklaması ya da null. Bkz. WhatsApp için reklam tıklaması ilişkilendirmesi.
campaign Kişinin oluşturulduğu klasik kampanya ya da null (kişiler artık temsilciler tarafından yönetildiğinden güncel değer budur).
agent Kişiye atanan temsilci ya da null.
user Kişinin sahibi olan hesabın temel kimlik bilgileri.

“Test” örneği ile gerçek bir olay biraz farklı görünür. Test düğmesi yer tutucu veriler (John Doe, örnek bir kampanya bloğu) gönderir. Gerçek bir Kişi Oluşturuldu olayı, gerçek kişinin ayrıntılarını taşır ve kanala bağlı olarak bazı alanlar boş olabilir.


Yeni Mesaj Webhook

Bu web kancası, herhangi bir kanalda bir konuşmaya mesaj eklendiğinde tetiklenir. Her iki yönü de kapsar: kişinizin size gönderdiği mesajlar ve yapay zeka temsilcinizin, ekibinizin veya bir yayının onlara gönderdiği mesajlar. Mesaj metnini içeren tek web kancası budur, bu nedenle konuşmaları harici bir sisteme yansıtmak istediğinizde kullanılması gereken kancadır.

Olay adı

new_message

Yük formatı

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web",
    "media_url": null,
    "media_content_type": null
  }
}
Alan Açıklama
event Bu olay için her zaman new_message. Bunun gönderilen tam dizi olduğunu unutmayın; “Yeni Mesaj” görünen etiketi değildir.
contact Mesajın ait olduğu konuşmanın kişisi. Kişi Oluşturuldu bölümündekiyle aynı yapıdadır.
agent Konuşmayı yöneten temsilci (id ve name) veya hiçbir temsilci dahil değilse null.
user Konuşmanın sahibi olan hesap için temel kimlik bilgileri.
message.id Mesajın benzersiz kimliği.
message.body Mesaj metni. Ekli bir mesaj için gövde, neyin ulaştığına dair köşeli parantez içinde bir notla başlar, ardından varsa altyazı gelir; örneğin [THE CONTACT UPLOADED AN IMAGE] Here is my CV, [THE CONTACT UPLOADED A DOCUMENT] veya [THE CONTACT UPLOADED A VOICE NOTE] - [TRANSCRIPTION: ...]. Sesli notlar ve videolar transkripsiyonu içerir.
message.direction Kişiden gelen bir mesaj için inbound, yapay zekanız veya ekibiniz tarafından gelen kutusundan gönderilen bir mesaj için outbound ve bir yayın (klasik kampanya dahil), şablon gönderimi veya API tarafından gönderilen bir mesaj için outbound-api.
message.status Mesajın yaşam döngüsünde nerede olduğu: gelen için received ve giden için queued / sent / delivered / read / failed / undelivered. Bu, mesajın oluşturulduğu andaki durumdur, bu nedenle giden bir mesaj buraya genellikle queued veya sent olarak ulaşır ve sonrasında delivered durumuna gelir — bu sonraki geçişlere ihtiyacınız varsa Teslimatlar ve Okumalar olaylarını kullanın. Bunlar bu blokla aynı message.id değerini taşır, böylece geçişi bu mesajla eşleştirebilirsiniz (bkz. Teslimatlar ve Okumalar Web Kancası).
message.created_at Mesajın oluşturulduğu zaman, UTC (ISO 8601) cinsinden.
message.channel Mesajın geçtiği kanal; örneğin whatsapp, whatsapp_web, sms, instagram, messenger, telegram, email veya custom.
message.media_url Mesaja ekli dosya (görüntü, sesli not, video veya belge) için bir indirme bağlantısı veya yoksa null. Her zaman mevcuttur.
message.media_content_type Dosyanın türü; örneğin image/jpeg, audio/ogg veya application/pdf. media_url, null olduğunda null.

Bu yükte hala campaign bloğu yok. Yeni Mesaj; contact, agent, user ve message gönderir. agent bloğu 15 Ağustos 2026 tarihinde eklendi ve size konuşmayı hangi temsilcinin yönettiğini söyler; kişi hakkında daha fazla bağlama ihtiyacınız varsa, contact.id kullanarak API üzerinden arama yapın.

Ekleri ulaştıktan kısa bir süre sonra kaydedin. media_url bağlantısı, mesaj ulaştıktan 7 gün sonra her kanalda (WhatsApp Business API, WhatsApp Web, Instagram, Messenger, Telegram, sohbet penceresi ve diğerleri) çalışmayı durdurur; dosyanın kendisi kalır. Daha sonra yeni bir bağlantı almak için contacts/{contact.id}/messages/{message.id} ile Bir mesajın ekini indirin çağrısını yapın. Alanlar 13 Eylül 2026 tarihinde eklenmiştir.

media_url değeri null olduğunda ancak gövde kısmında bir dosyanın geldiği belirtildiğinde. Bazı ekler doğrudan bağlantısı olmayacak şekilde depolanır; paylaşılan bir Instagram reel’i, gönderisi veya hikaye bahsetmesi bir dosyaya değil Instagram’a giden bir bağlantıdır, bu nedenle bunlar da null olarak gelir (gövde kısmında neyin paylaşıldığı belirtilir). Bir dosya için, bağlantı almak üzere mesajın kimliğiyle Bir mesajın ekini indir işlevini çağırın.

İçe aktarılan geçmiş bu web kancasını tetiklemez. Bir WhatsApp Web numarası geçmiş konuşmalarını içe aktardığında, bu eski mesajlar her biri için bir Yeni Mesaj bildirimi oluşturulmadan kaydedilir.

Dahili yapay zeka kayıtları bu webhook’u tetiklemez. Platform, gerçek mesajların yanı sıra bir görüşmede kendi kayıt tutma satırlarını (yapay zekanın araç çağrıları ve dahili sıra kayıtları) tutar. Bunlar asla gönderilmez — yalnızca gerçekten gönderilen veya alınan mesajları alırsınız.


Teslimatlar ve Okundu Bilgileri Webhook’u

Bu iki etkinlik, bir mesaj Your AI Connector'dan ayrıldıktan sonra ne olduğunu bildirir: Teslimatlar, bir mesaj kişiye ulaştığında (veya ulaşamadığında) tetiklenir ve Okundu Bilgileri, okundu bilgisini destekleyen kanallarda kişi mesajı açtığında tetiklenir.

Her ikisi de, güncellemeyi gönderdiğiniz tam mesajla eşleştirebilmeniz için, etkinliğin ilgili olduğu mesajın kimliğini içeren bir message bloğu taşır.

Etkinlik adları

Teslimatlar için delivered ve undelivered, Okundu Bilgileri için read.

Yük formatı

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}
Alan Açıklama
event Teslimatlar için delivered veya undelivered, Okumalar için read.
contact Mesajın gönderildiği kişi.
campaign Kişinin ait olduğu klasik kampanya veya null (kişiler artık temsilciler tarafından yönetildiğinden güncel değer budur).
agent Konuşmayı yöneten temsilci veya null.
user Verilerin sahibi olan hesap için temel kimlik bilgileri.
message.id Bu güncellemenin ilgili olduğu mesajın kimliği. mesaj gönder uç noktası tarafından messageId olarak döndürülen değerle ve bir Yeni Mesaj bildiriminin taşıdığı message.id ile aynı değerdir.
message.status Yeni durum, her zaman event ile aynı dize (delivered, undelivered veya read).

Bir güncellemeyi gönderdiğiniz mesajla nasıl eşleştirirsiniz. API aracılığıyla bir mesaj gönderdiğinizde geri aldığınız messageId değerini saklayın. Bir Teslimatlar veya Okundu Bilgileri bildirimi geldiğinde, yükteki message.id değerine karşı o saklanan kimliği arayın — bu, o tam mesaj için teslimat veya okundu bilginizdir.

Burada mesaj metni yok. message bloğu yalnızca kimliği ve durumu taşır. Ayrıca gövdeye de ihtiyacınız varsa Yeni Mesaj etkinliğine abone olun.

message bloğu yalnızca hangi mesaj olduğunu bildiğimizde mevcuttur. Saklanan bir mesajla ilişkilendiremediğimiz nadir güncellemelerde, blok boş gönderilmek yerine tamamen dışarıda bırakılır — bu nedenle message.id değerini okumadan önce message değerinin var olup olmadığını kontrol edin.

Durum değişikliği başına bir bildirim. Tek bir giden mesaj normalde bir delivered bildirimi ve ardından, okundu bilgisi olan kanallarda, bir read bildirimi üretir. Başarısız bir gönderim bunun yerine undelivered üretir.


Randevu Alındı Webhook

Bir kişi randevu aldığında tetiklenir. Yapay zekanın bir konuşma sırasında randevu alması, sizin manuel olarak randevu almanız veya API aracılığıyla gelmesi durumunda aynı şekilde tetiklenir.

Olay adı

booked

Yük formatı

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "external_reference": "crm-booking-1042",
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}
Alan Açıklama
event Bu etkinlik için her zaman booked değerindedir.
contact Rezervasyonu yapan kişi. Kanal durumuna bağlı olarak email ve phone_number boş olabilir.
appointment.appointment_id Rezervasyonun benzersiz kimliği.
appointment.start_time / end_time Rezervasyon yapılan zaman diliminin başlangıcı ve bitişi, UTC (ISO 8601) formatında.
appointment.status Rezervasyonun mevcut durumu.
appointment.room_name Eğer kullanılıyorsa, rezervasyonun yapıldığı oda.
appointment.description / summary Rezervasyonla birlikte alınan serbest metin detayları.
appointment.google_calendar_event_id Senkronize edilen etkinlik için Google Takvim kimliği. Randevu Alındı (Appointment Booked) webhook’unda genellikle null değerindedir, çünkü takvim etkinliği bildirim gönderildiği anda oluşturulur — ihtiyacınız varsa randevuyu bir an sonra appointment_id ile tekrar getirin ve Google Takvim bağlantısı olmayan hesaplarda kalıcı bir null bekleyin.
appointment.external_reference Rezervasyonun API aracılığıyla oluşturulurken kendi sisteminizden aldığı kimlik veya null.
appointment.event Rezervasyonu yapılan hizmet: ad, zaman dilimi uzunluğu, konum, toplantı bağlantısı, tür.

google_calendar_event_id bu webhook’ta genellikle null’dir ve bu normaldir. Google Takvim etkinliği, bu bildirim gönderildiği anda oluşturulur, bu nedenle kimlik genellikle henüz hazır değildir. İhtiyacınız varsa, bir an sonra appointment_id ile randevuyu tekrar getirin. Hesapta bağlı bir Google Takvim yoksa kalıcı olarak null kalır, bu yüzden sonsuza kadar beklemeyin.

“Test” düğmesi, sahte değerlerle örnek bir appointment bloğu gönderir, böylece gerçek bir randevu gelmeden önce yapıyı oluşturabilirsiniz.

Bu webhook’un tetiklenmediği iki durum: harici bir takvimden içe aktarılan randevular ve Formitable entegrasyonu aracılığıyla gelen rezervasyonlar.


Randevu İptal Edildi ve Yeniden Planlandı Webhook’ları

Randevu İptal Edildi, bir randevu iptal edildiğinde; Randevu Yeniden Planlandı ise yeni bir başlangıç veya bitiş zamanına taşındığında tetiklenir. Her ikisi de, yapay zeka bir görüşme sırasında yapmış olsa, siz uygulamada değiştirmiş olsanız, API aracılığıyla gelmiş olsa veya birisi bağlı Google Takvim’de etkinliği değiştirmiş olsa bile aynı şekilde tetiklenir.

Etkinlik adları

appointment_cancelled ve appointment_rescheduled

Yük formatı

Gövde, değişiklikten sonraki randevu ile Randevu Alındı ile aynıdır. İptal işlemi appointment.cancelation_reason ekler; yeniden planlama, eski zamanları içeren üst düzey bir previous bloğu ekler:

{
  "event": "appointment_rescheduled",
  "contact": { "id": "<contact-id>", "email": "jane@example.com", "phone_number": "+15551234567", "first_name": "Jane", "last_name": "Smith" },
  "campaign": null,
  "agent": { "id": "<agent-id>", "name": "Front desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-21T09:00:00.000Z",
    "end_time": "2026-07-21T09:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": "<calendar-event-id>",
    "external_reference": "crm-booking-1042",
    "cancelation_reason": null,
    "event": { "id": "<service-id>", "event_name": "Intro Call", "slot_duration": 30 }
  },
  "previous": {
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z"
  }
}
Alan Açıklama
event appointment_cancelled veya appointment_rescheduled.
appointment.status İptal durumunda Canceled (bir l, API’nin döndürdüğü değer), yeniden planlama durumunda Confirmed.
appointment.cancelation_reason Randevu iptal edildiğinde verilen neden veya null.
appointment.start_time / end_time Değişiklikten sonraki zaman dilimi, UTC (ISO 8601) cinsinden.
previous.start_time / previous.end_time Yalnızca yeniden planlama: randevunun taşındığı önceki zaman dilimi.
campaign / agent Kişinin mevcut kampanyası ve temsilcisi veya null.

Bir değişiklik, bir etkinlik. Bir randevuyu iptal etmek, aynı düzenlemede saati değişse bile yalnızca Randevu İptal Edildi etkinliğini gönderir. Yalnızca başlığı, notları veya odayı düzenlemek hiçbirini göndermez. Aynı randevuyu iki kez taşımak, iki Randevu Yeniden Planlandı etkinliği gönderir.


Sohbet Sonlandırıldı Web Kancası

Yapay zeka bir konuşmanın sona erdiğine karar verdiğinde (rezervasyon yapıldı, bir potansiyel müşteri elendi vb.) tetiklenir.

Olay adı

chat_concluded

Yük formatı

Yük; event, tam contact, sohbeti yöneten agent ve hesap user değerlerini taşır. Ayrıca, n8n veya Make akışının ikinci bir çağrı yapmadan günlüğe kaydedebilmesi için bu konuşmanın kredi cinsinden maliyeti olan conversation_cost değerini de taşır:

{
  "event": "chat_concluded",
  "contact": { "id": "abc123", "first_name": "Jane", "channel": "whatsapp" },
  "agent": { "id": "agent_1", "name": "Sales Agent" },
  "user": { "id": "user_1" },
  "conversation_cost": {
    "credits": 7.5,
    "session_id": "sess_9f2",
    "started_at": "2026-09-26T09:14:02.000Z",
    "outcome": "contained"
  }
}
  • credits: bu konuşma içinde tahsil edilen krediler, iadeler düşülmüştür. API’deki konuşma maliyetleri raporuyla aynı şekilde hesaplanır.
  • outcome: contained (yapay zeka tek başına yönetti), handed_off (yapay zekadan sonra ekibinizden biri yanıt verdi veya yapay zeka bir insanı uyardı) veya no_ai.
  • conversation_cost, rakamın o anda hesaplanamadığı durumlarda boş bırakılır. İsteğe bağlı olarak değerlendirin.

Kişi Etiketleri Güncellendi Webhook’u

Bir kişiye etiket uygulandığında ve o etiketin, kişinin atandığı temsilci üzerinde yapılandırılmış bir web kancası URL’si olduğunda tetiklenir.

Olay adı

contact_tags_updated

Ne zaman tetiklenir

  • Bir yapay zeka temsilcisi atanmış bir kişiye etiket uygulanır.
  • Uygulanan etiketlerden en az birinin, o temsilcinin düzenleyicisindeki Etiketler sekmesinde ayarlanmış bir webhook URL’si vardır.

Temsilcilere geçişten önceki klasik bir kampanyaya hala bağlantısı olan bir kişi özel bir durumdur: eğer o kampanyanın etiketleri webhook URL’leri taşıyorsa, bunlar kullanılır; aksi takdirde temsilcininkiler kullanılır.

Aynı güncelleme içerisinde farklı webhook URL’lerine sahip birden fazla etiket uygulanırsa, her URL için bir istek gönderilir ve her biri yalnızca o URL ile eşleşen etiketleri içerir.

Bir etiketin kaldırılması asla istek göndermez. Çoğu kişi bu URL’leri bir eyleme (depozito toplama, yer ayırtma, temsilciyi uyarma gibi) yönlendirir; bu nedenle bir etiketin bir kişiden kaldırılması, o eylemin yeniden çalıştırılması için kullanılırdı. Artık bu mümkün değildir. Bir kaldırma işlemi, aynı URL’ye giden bir uygulama ile aynı güncellemede gerçekleştiğinde removed_tags içinde görünmeye devam eder, böylece her iki diziyi de okuyan bir otomasyon tam resmi görebilir; ancak asla yalnızca kaldırma işleminden kaynaklanan bir istek görmeyecektir. (12 Ağustos 2026 tarihinde değiştirilmiştir. Bu tarihten önce, kaldırma işlemleri de istek gönderiyordu.)

Yük formatı

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    },
    "ad_attribution": null
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}
Alan Açıklama
event Bu web kancası için her zaman contact_tags_updated değerindedir.
contact.id Etiketleri değişen kişinin benzersiz kimliği.
contact.email / contact.phone_number Biliniyorsa kişinin e-postası/telefonu.
contact.first_name / contact.last_name Kişinin adı.
contact.human_alerted Kişinin şu anda insan müdahalesi için işaretlenip işaretlenmediği.
contact.is_bot_active Yapay zeka botunun bu kişinin konuşmasında şu anda aktif olup olmadığı.
contact.ad_referral Yalnızca kişi size bir Meta reklamı (Click-to-WhatsApp, Click-to-Instagram veya Click-to-Messenger) veya bir WhatsApp gönderi yönlendirmesi aracılığıyla ulaştığında mevcuttur. Aksi takdirde null. Bkz. Click-to-WhatsApp Reklam İlişkilendirmesi.
contact.ad_attribution Yalnızca kişi, reklam tıklama betiği tarafından kaydedilen ve web sitenize yönlendiren bir reklam tıklamasıyla eşleştiğinde mevcuttur. Aksi takdirde null.
added_tags Bu güncellemede uygulanan etiket adları dizisi. Asla boş değildir; isteği tetikleyen şey bir uygulama işlemidir.
removed_tags Varsa, aynı güncellemede kaldırılan etiket adları dizisi. Tek başına bir kaldırma işlemi herhangi bir şey göndermez.
agent Kişinin konuşmasını yöneten temsilci (id ve name) veya hiçbir temsilci dahil değilse null. 15 Ağustos 2026 tarihinde eklendi.
user Kişinin sahibi olan hesabın temel kimlik bilgileri.

Bir etiket webhook’unu test etme

Etiketler sekmesindeki webhook URL alanının yanında bir Test düğmesi bulunur. Bu düğme, gerçek bir konuşmayı beklemeden otomasyonunuzun veriyi aldığını doğrulayabilmeniz için o URL’ye hemen örnek bir yük gönderir.

Test, yukarıda gösterilen contact_tags_updated şekliyle, yer tutucu bir kişi kullanarak, test ettiğiniz etiket added_tags içinde ve boş bir removed_tags ile gönderilir. Otomasyonunuzun testte gördüğü şey, üretim ortamında da göreceği şeydir.

Bilmeniz gereken iki şey:

  • Önce etiketi kaydedin. Test, etiketi kayıtlı adına göre arar, bu nedenle yepyeni bir etiket veya kaydedilmemiş bir yeniden adlandırma henüz test edilemez. Düğme, ekrandaki ad kayıtlı olanla eşleşene kadar gri kalır.
  • Başarısız bir test web kancanıza karşı sayılmaz. Testler, Web Kancası Güvenilirliği bölümünde açıklanan tekrarlanan hatalardan sonra otomatik kapanmaya hiçbir zaman katkıda bulunmaz. Test başarısız olursa, ileti size uç noktanızın ne yanıt verdiğini söyler (örneğin bir 404 veya 500), bu genellikle yanlış bir URL’yi veya açık olmayan bir iş akışını tespit etmek için yeterlidir.

Görev Tamamlandı Webhook’u

Yalnızca referans içindir. Görev webhook’ları (veri olarak) geliştiriciler için belgelenmiştir; Görev Oluşturuldu, Görev Güncellendi ve Görev Tamamlandı etkinlikleri, webhook formundaki standart etkinlik listesinde diğer tüm etkinlikler gibi seçilebilir — bkz. Mevcut Tetikleyici Etkinlikler ve 24 Webhook Etkinliği.

Bu yük (payload), bir görev tamamlama aşaması olarak işaretlenmiş bir aşamaya geçtiğinde gönderilir. Tamamlama dışı aşamalar arasında hareket eden bir görev bunun yerine taskUpdated biçimini gönderir.

Olay adı

taskCompleted

Ne zaman tetiklenir

  • Bir görev güncellendiğinde.
  • stage değeri önceki değerine kıyasla değiştiğinde.
  • Yeni aşama, hesabın görev aşaması ayarlarında bir tamamlama aşaması olarak yapılandırıldığında.

Yük formatı

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}
Alan Açıklama
event Bu webhook için her zaman taskCompleted değerindedir. Bir görev, tamamlama aşamasına girmeden değiştiğinde taskUpdated ile aynı yük biçimi gönderilir.
contact Varsa, görevle bağlantılı kişi. Bağlı olmadığında null değerindedir.
contact.human_alert_reason Varsa, kişinin insan ilgisi için işaretlenme nedeni.
user Görevin sahibi olan hesap için temel kimlik bilgileri.
message.id Görevin benzersiz kimliği (ID).
message.title / description Görevin başlığı ve açıklaması.
message.type Görev türü (örneğin, follow_up, call, custom).
message.priority Görev önceliği (low, medium, high).
message.stage Görevin şu anda bulunduğu aşamanın kimliği.
message.due_date Ayarlanmışsa, görevin son teslim tarihi.
message.source Görevi neyin oluşturduğu: manual, human_alert, ai_tool, api, automation, daily_summary, chat veya chat_composer.
message.source_detail Kaynak hakkında ek detay.
message.campaign_id Bağlı klasik kampanyanın kimliği veya null.
message.linked_human_alert Varsa, bağlı insan uyarısının kimliği.
message.tags Göreve uygulanan etiketler.
message.notes Görevle ilgili serbest biçimli notlar.

Bir Webhook’u Kapatma (veya Silme)

Her webhook’un kendi satırında bir açma/kapama düğmesi bulunur. Birini kapalı konuma getirmek, etkinlik almayı durdurur ancak yapılandırdığınız her şeyi (URL, etkinlikler, herhangi bir imzalama gizli anahtarı) korur. Tekrar açtığınızda kaldığı yerden devam eder; kapalı olduğu süre boyunca gerçekleşen hiçbir şey sonradan iletilmez.

Bunu, iletimlerin bir süreliğine durmasını istediğinizde kullanın: uç noktanız yeniden oluşturuluyorsa, gürültülü bir entegrasyonda hata ayıklıyorsanız veya bir otomasyonu duraklatıyorsanız.

Bir webhook’u silmek (satırındaki çöp kutusu simgesi), imzalama gizli anahtarı da dahil olmak üzere onu kalıcı olarak kaldırır. Yalnızca teslimatların durmasını istiyorsanız, bunun yerine kapatın; silme işlemi, uç noktayla işiniz tamamen bittiğinde kullanılır.

Bu, bir web kancasının otomatik olarak kapatılmasıyla aynı şey değildir. Web kancanızı tekrarlanan başarısızlıklar sonrasında devre dışı bırakırsak (bkz. Web Kancası Güvenilirliği), yukarıdaki açma/kapama düğmesi onu geri getirmez. Uç noktanız düzeltildiğinde, web kancasını düzenleyin ve değiştirilmiş bir URL ile kaydedin (herhangi bir URL değişikliği onu yeniden etkinleştirir) veya API üzerinden yeniden etkinleştirme uç noktasını çağırın ya da destek ekibimizle iletişime geçin, sizin için tekrar açalım.


İmzalı Yükler (Bir Webhook’un Gerçekten Bizden Geldiğini Doğrulama)

Webhook URL’nizi öğrenen herkes ona sahte bir istek gönderebilir. Webhook’lar üzerinde otomatik olarak işlem yapıyorsanız (faturalandırmayı güncelleme, CRM kayıtları oluşturma gibi), imzalamayı açmak her isteğin gerçekten bizden geldiğini doğrulamanızı sağlar.

İmzalama isteğe bağlıdır ve varsayılan olarak kapalıdır; bunu webhook başına, o webhook’un düzenleme görünümünden (kaydedilmiş bir webhook’un satırını açarak) açarsınız.

İmzalama özelliğini açma

  1. Webhook’u açın (Ayarlar → Entegrasyonlar → Webhook’lar → webhook’unuzun satırına tıklayın).
  2. İmzalama gizli anahtarı bölümünde Oluştur’a tıklayın.
  3. Gizli anahtarı kopyalayın ( whsec_ ile başlar) ve alıcı sisteminizde saklayın. Ona bir parola gibi davranın.

İstediğiniz zaman bu aynı panelden geri gelip gizli anahtarı görüntüleyebilir, kopyalayabilir, döndürebilir veya kapatabilirsiniz.

Ne gönderiyoruz

İmzalama açıldığında, bu webhook için yapılan her teslimat şu iki ek HTTP başlığını taşır:

Başlık Anlamı
X-Webhook-Signature v1=<hex> biçimindeki imza.
X-Webhook-Timestamp Saniye cinsinden Unix zaman damgası olarak gönderdiğimiz zaman.

Bu üçü, imzalı olsun veya olmasın her teslimatta bulunur:

Başlık Anlamı
X-Webhook-Delivery Bu etkinlik için benzersiz bir kimlik. Yeniden denemelerde aynı kalır, bu yüzden tekilleştirme (dedupe) işlemini bunun üzerinden yaparsınız.
X-Webhook-Attempt Bunun kaçıncı deneme olduğu (1 ilk denemedir).
X-Webhook-Event Etkinlik adı, böylece içeriği okumadan yönlendirme yapabilirsiniz.

Nasıl doğrulanır

İmza, imzalama gizli anahtarınız anahtar olarak kullanılarak <timestamp>.<raw request body> dizisinin HMAC-SHA256 değeridir.

Ham istek gövdesine karşı doğrulama yapın — aldığınız tam baytlar. Çerçeveniz JSON’u ayrıştırıp kontrol etmeden önce yeniden serileştirirse, baytlar değişebilir ve imza eşleşmeyebilir.

Node.js örneği:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Python örneği:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

İmzaları zamanlama açısından güvenli bir işlevle (timingSafeEqual / compare_digest) karşılaştırın, == ile değil. Bunun hiçbir maliyeti yoktur ve ince bir saldırı sınıfını önler.

Gizli anahtarı döndürme

Gizli anahtarı değiştirmek için Döndür’e tıklayın. Geçiş anlıktır: bir sonraki teslimat yalnızca yeni gizli anahtarla imzalanır. Uç noktanız canlıysa, yenisini dağıtana kadar birkaç dakika boyunca hem eski hem de yeni gizli anahtarı kabul edin.

İmzalamayı kapatmak, imza başlıklarının gönderilmesini durdurur.


Başarısız Teslimatları Yeniden Deneme

Varsayılan olarak, başarısız olan bir teslimat yeniden denenmez; sisteminiz o anda kapalıysa, o etkinlik kaçırılmış olur.

Bir webhook üzerinde (oluşturma/düzenleme formunda) Başarısız teslimatları yeniden dene seçeneğini açın, biz de denemeye devam edelim:

Deneme Zaman
1 Hemen
2 1 dakika sonra
3 5 dakika sonra
4 30 dakika sonra
5 2 saat sonra

Bu süre yaklaşık 2 saat 40 dakika sürer, böylece bir webhook bakım penceresini veya tarafınızdaki kısa bir kesintiyi atlatabilir.

Neler yeniden denenir: geçici sorunlar — sunucunuzun 5xx hatası döndürmesi, zaman aşımı veya bağlantı hatası.

Neler yeniden denenmez: uç noktanız isteği reddederse (herhangi bir 4xx hatası), yeniden deneme yapmayız; aynı isteği tekrar göndermek yalnızca aynı reddedilme sonucunu doğuracaktır.

Hangi etkinlikler yeniden denenir: 24 Eylül 2026 tarihinden itibaren gerçekleşen her etkinlik. Bu kapsamda etiket web kancaları (contact_tags_updated), üç görev etkinliği, günlük özet, özet web kancası, Yeni Mesaj, Sohbet Sonlandırıldı, Kişi Duraklatıldı, Kişi Devam Ettirildi, Kişi Rahatsız Etme, Kişi Arşivden Çıkarıldı, Düşük Kredi Bakiyesi, Yayın etkinlikleri ve şu kişi ve etkinlik olayları yer alır: Kişi Oluşturuldu, Randevu Alındı, İnsan Uyarısı, Yanıtlar, Okumalar, Teslimatlar, Harcanan Krediler ve Yüklenen Krediler. Bu tarihten önce Yeni Mesaj, Sohbet Sonlandırıldı, Kişi Duraklatıldı, Kişi Devam Ettirildi, Kişi Rahatsız Etme, Kişi Arşivden Çıkarıldı ve özet web kancası, anahtarın durumuna bakılmaksızın bir kez gönderiliyordu. Her etkinlik X-Webhook-Delivery içerir, bu nedenle tek bir tekilleştirme kuralı hepsini kapsar.

Yeniden denemeleri yalnızca uç noktanız idempotent (eşgüçlü) ise açın. Yeniden denemeler, aynı etkinliğin birden fazla kez gelebileceği anlamına gelir. Bir tekrarı tanımak için X-Webhook-Delivery başlığını kullanın: bu başlık, bir etkinlik için yapılan her denemede aynı kalır, böylece zaten işlediğiniz bir kimliği güvenle göz ardı edebilirsiniz.

Yeniden denemeler, tekrarlanan başarısızlıkların ardından otomatik kapatma özelliğiyle (bkz. Web Kancası Güvenilirliği) tam istediğiniz şekilde etkileşime girer: başarısızlık sayacı, her bir denemeyi değil, yalnızca tüm yeniden denemeler kullanıldıktan sonra tüm teslimatı sayar.


Webhook Güvenilirliği

  • Your AI Connector, web kancalarını güvenli bir bağlantı (HTTPS) üzerinden gönderir. Sağladığınız web adresinin HTTPS kullandığından emin olun.
  • Sisteminiz bir hata döndürürse, teslimat başarısız kabul edilir.
  • Etkinlikleri kaçırmamak için alıcı sisteminizin çalışma süresini izleyin.
  • Kritik iş akışları için Başarısız Teslimatları Yeniden Deneme özelliğini açın ve ayrıca bir yedekleme mekanizması düşünün.

Web kancaları, tekrarlanan başarısızlıklar sonrasında otomatik olarak kapatılır. Web kancası URL’niz sürekli olarak başarısız olursa (arka arkaya yaklaşık 5 hata veya yapılandırma türü hatalar için arka arkaya 3 hata), Your AI Connector bu URL’ye etkinlik göndermeyi otomatik olarak durdurur. Uç noktanız sağlıklı hale geldiğinde onu geri getirmek için: web kancasını düzenleyin ve değiştirilmiş bir URL ile kaydedin (herhangi bir URL değişikliği onu yeniden etkinleştirir) veya API üzerinden yeniden etkinleştirme uç noktasını kullanın; aynı URL ile yeniden kaydetmek yeterli değildir. Destek ekibi de sizin için yeniden etkinleştirebilir.


Sorun Giderme

Sorun Çözüm
Webhook tetiklenmiyor Öncelikle webhook’un kendi satırında kapalı olmadığından emin olun. Ardından doğru olayların seçildiğini ve URL’nizin internetten erişilebilir olduğunu doğrulayın.
Test olayı çalışıyor ancak gerçek olaylar çalışmıyor Belirli olay türünün etkinleştirildiğinden emin olun. Bir etiket uygulandığında istek bekliyorsanız, subscribed_to_tags ifadesinin bir webhook’un olaylarını bir etiketle sınırlamadığını, yalnızca hangi etiketlerin konuşma özeti bildirimi üreteceğini daralttığını unutmayın. Belirli bir etiket uygulandığında istek almak için, temsilci düzenleyicisinin Etiketler sekmesinde o etikete bir webhook URL’si ayarlayın. Bkz. Kişi Etiketleri Güncellendi Webhook’u.
n8n / Make / Zapier’e hiçbir şey ulaşmıyor Muhtemelen platformun, "Test olayını dinle"ye tıkladıktan hemen sonra yalnızca tek bir olayı dinleyen Test URL’sini kullanıyorsunuz. Canlı olaylar için Üretim URL’sini kaydedin ve iş akışını Aktif konuma getirin.
Yinelenen olaylar alınıyor Aynı URL’yi işaret eden birden fazla webhook olup olmadığını kontrol edin. Başarısız teslimatları yeniden dene açıksa, uç noktanız bir olayı kabul edip zamanında yanıt veremediğinde bir tekrar beklenir — X-Webhook-Delivery üzerinde tekilleştirme yapın.
İmza kontrolü her zaman başarısız oluyor Neredeyse her zaman gövde kontrol edilmeden önce yeniden serileştirildiği içindir. Ham istek gövdesine göre doğrulayın, <timestamp>.<body> imzalayın ve yakın zamanda değiştirdiyseniz güncel gizli anahtarı kullandığınızdan emin olun.
Yeniden denemeler gerçekleşmiyor O belirli webhook’ta etkinleştirilmediği sürece yeniden denemeler kapalıdır. 4xx yanıtlarını yeniden denemiyoruz.
campaign bloğu her zaman null Beklenen: kişiler bir kampanya yerine bir yapay zeka temsilcisiyle oturur. Bunun yerine agent bloğunu okuyun. Bkz. Webhook Veri Formatı.
Veri boş veya hatalı biçimlendirilmiş Alıcı sisteminizin JSON kabul ettiğini doğrulayın. Ayrıştırma hataları için sunucu günlüklerinizi kontrol edin.
Webhook URL’si hatalar döndürüyor URL’nizi Postman veya webhook.site gibi bir araçla test edin.
Webhook bir kesintiden sonra tamamen tetiklenmeyi durdurdu Tekrarlanan hatalar bir webhook’u otomatik olarak devre dışı bırakır. Yeniden kaydetmek onu tekrar etkinleştirmez — uç noktanızı düzeltin, ardından destek ekibiyle iletişime geçin.
Kaydetme veya Test etme izin hatası veriyor Entegrasyonlar “düzenleme” iznine ihtiyacınız var. Hesap sahibinden bunu vermesini isteyin.
Bir webhook’un subscribed_to_tags listesi boş döndü subscribed_to_tags, bir webhook’un olaylarını bir etiketle sınırlamaz; yalnızca hangi etiketlerin konuşma özeti bildirimi üreteceğini daraltır. Webhook formundan düzenleme yapmak artık o listeyi temizlemiyor (21 Temmuz 2026’da düzeltildi). Bir webhook bu tarihten önce listesini kaybettiyse, Webhooks API aracılığıyla subscribed_to_tags değerini tekrar ayarlayın — bkz. Etiket Tabanlı Webhook Tetikleyicileri.

Sonraki Adımlar