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
- Sol kenar çubuğunda Ayarlar’a (dişli simgesi) tıklayın.
- 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:
- Sağ üst köşedeki New webhook (Yeni webhook) düğmesine tıklayın. Sayfa içinde bir form açılacaktır:
- Ş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üzhttp://adresleri,localhostveya ö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.
- 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.
- (İ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.
- 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:
userbloğu, bir etkinliğin hangi müşteriye ait olduğunu size bildirir. Her bildirim, etkinliğin gerçekleştiği hesabı tanımlayan biruserbloğ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_tagslistesine 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 öncesubscribed_to_tagslistesini 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
- Ayarlar → Entegrasyonlar → Webhook’lar yolunu izleyin.
- Webhook’unuzun satırında Test Et düğmesine tıklayın.
- Test verilerini alıp almadığını doğrulamak için harici sisteminizi kontrol edin.
- 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/jsoniç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=abc123tam 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.0kullanı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,-testiç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 veagentsize konuşmayı hangisinin yönettiğini söyler.campaignalanı, eski alıcıların çalışmaya devam etmesi için hala gönderilmektedir ancak genelliklenulldeğerindedir; yalnızca hala klasik bir kampanyaya bağlantı taşıyan bir kişi için doldurulur.campaigndeğerinin her zaman orada olduğunu varsaymayın.
agentbloğu 15 Ağustos 2026 tarihinde geldi. Bu blok, bir konuşmaya bağlı olaylar olancampaign(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 temsilcininidvenamebilgilerini veya temsilci dahil olmadığındanulldeğ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
idvestatusdeğerlerini içeren birmessagebloğu taşır — ve buid, mesaj gönderme uç noktasının geri döndürdüğümessageIdile 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çbirmessagebloğ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.
timestampalanı yoktur vedatasarmalayı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
campaignbloğu yok. Yeni Mesaj;contact,agent,uservemessagegönderir.agentbloğ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.idkullanarak API üzerinden arama yapın.
Ekleri ulaştıktan kısa bir süre sonra kaydedin.
media_urlbağ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çincontacts/{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_urldeğerinullolduğ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 danullolarak 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
messageIddeğerini saklayın. Bir Teslimatlar veya Okundu Bilgileri bildirimi geldiğinde, yüktekimessage.iddeğerine karşı o saklanan kimliği arayın — bu, o tam mesaj için teslimat veya okundu bilginizdir.
Burada mesaj metni yok.
messagebloğu yalnızca kimliği ve durumu taşır. Ayrıca gövdeye de ihtiyacınız varsa Yeni Mesaj etkinliğine abone olun.
messagebloğ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 nedenlemessage.iddeğerini okumadan öncemessagedeğerinin var olup olmadığını kontrol edin.
Durum değişikliği başına bir bildirim. Tek bir giden mesaj normalde bir
deliveredbildirimi ve ardından, okundu bilgisi olan kanallarda, birreadbildirimi üretir. Başarısız bir gönderim bunun yerineundeliveredü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_idbu webhook’ta genelliklenull’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 sonraappointment_idile randevuyu tekrar getirin. Hesapta bağlı bir Google Takvim yoksa kalıcı olaraknullkalır, bu yüzden sonsuza kadar beklemeyin.
“Test” düğmesi, sahte değerlerle örnek bir
appointmentbloğ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ı) veyano_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
404veya500), 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.
stagedeğ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
- Webhook’u açın (Ayarlar → Entegrasyonlar → Webhook’lar → webhook’unuzun satırına tıklayın).
- İmzalama gizli anahtarı bölümünde Oluştur’a tıklayın.
- 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-Deliverybaş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
- GoHighLevel Entegrasyonu — Your AI Connector'ı GHL ile entegre etmek için web kancalarını kullanın.
- API Erişimi — güçlü otomasyonlar için web kancalarını API ile birleştirin.
- Kişileri Etiketlemek İçin Etiketleri Kullanma — web kancalarınızı tetikleyen etiketleri ayarlayın.