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) yalnızca Your AI Connector dışına veri gönderir. Bir web kancası, Your AI Connector'den diğer araçlarınıza giden tek yönlü bir yoldur. Platformun İÇİNE potansiyel müşteri, kişi veya mesaj gönderen bir web kancası URL’si yoktur. Bir web sitesi formu, CRM’iniz veya GoHighLevel üzerinden yeni bir potansiyel müşteri eklemek için sisteminiz bunun yerine bir API çağrısı yapar. API Erişimi ( Kişi Oluştur işlemi) ve Huniler bölümlerine bakın. Gelen yön için ihtiyacınız olan tek şey, kendi bölümünde bulunan API anahtarınızdır; API Erişimi bölümüne bakın. Burada açıklanan Web kancaları sayfası yalnızca giden yön içindir.

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:

3. Sağ üst köşedeki New webhook (Yeni webhook) düğmesine tıklayın. Sayfa içinde bir form açılacaktır:

4. Ş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.

5. Etkinlikler altında, bu webhook’un almasını istediğiniz etkinlikleri tıklayın — 22 etkinliğin tamamı The 22 Webhook Events bölümünde listelenmiştir.
6. (İsteğe bağlı) Your AI Connector uygulamasının geçici bir hata durumunda yeniden deneme yapmasını istiyorsanız Başarısız teslimatları yeniden dene seçeneğini açın — Retrying Failed Deliveries bölümüne bakın.
7. Webhook oluştur düğmesine 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 #

22 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 (payload) içinde yer alan event kodu, bu sayfanın alt kısmındaki The 22 Webhook Events 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 etkinliklerini belirli 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, temsilcinin (veya kampanyanın) Etiketler sekmesindeki ilgili 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.

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" }
}

campaign veya agent — genellikle biri, ikisi birden değil. Hesabınız temsilciler kullanıyorsa, kişileriniz bir kampanya yerine bir temsilciye bağlıdır; bu nedenle campaign, null olarak gelir ve agent hangisinin ilgilendiğini belirtir. Kampanya tabanlı eski hesaplar bunun tersini görür. Hangisi doluysa onu okuyun; 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ı bir appointment bloğu ekler (bkz. Randevu Alındı Webhook’u), Yeni Mesaj metin içeren tam bir message bloğu ekler (bkz. Yeni Mesaj Webhook’u), Teslimatlar ve Okundu Bilgileri ise yalnızca mesajın kimliğini ve durumunu içeren kısa bir message bloğu ekler (bkz. Teslimatlar ve Okundu Bilgileri 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.

22 Webhook Etkinliği #

Uygulamada işaretlediğiniz görünen etiket ve yük (payload) içinde gönderilen event kodu ile birlikte 22 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:

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
  },
  "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"
  }
}

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

Yeni Mesaj Webhook #

Bu webhook, herhangi bir kanalda bir görüşmeye her mesaj eklendiğinde tetiklenir. Her iki yönü de kapsar: kişinizin size gönderdiği mesajlar ve yapay zekanızın, ekibinizin veya bir kampanyanın onlara gönderdiği mesajlar. Mesaj metnini içeren tek webhook budur, bu nedenle görüşmeleri harici bir sisteme yansıtmak istediğinizde kullanmanız gereken webhook budur.

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
  },
  "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"
  }
}

Bu yükte hala campaign bloğu bulunmamaktadır. Yeni Mesaj; contact, agent, user ve message gönderir. agent bloğu 15 Ağustos 2026 tarihinde eklenmiştir ve konuşmayı hangi temsilcinin yönettiğini size bildirir; kampanya bağlamına da ihtiyacınız varsa, contact.id kullanarak API üzerinden kişiyi aratın.

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
  },
  "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"
  }
}

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,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

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 appointment bloğunu içermez. Uç noktanızın yanıt verdiğini doğrulamak için kullanın, ardından tam yükü görmek için bir gerçek randevu oluşturun.

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

Kişi Etiketleri Güncellendi Webhook’u #

Bir kişiye etiket uygulandığında ve bu etiketin, kişinin ait olduğu temsilci veya kampanya üzerinde yapılandırılmış bir webhook URL’si olduğunda tetiklenir.

Olay adı #

contact_tags_updated

Ne zaman tetiklenir #

• Bir kişiye, kendisine atanmış bir temsilcisi, kampanyası veya her ikisi birden olan bir etiket uygulandığında.
• Uygulanan etiketlerden en az birinin, ilgili temsilci veya kampanyanın Etiketler sekmesinde ayarlanmış bir webhook URL’si olduğunda.

Kişinin her ikisi de varsa ve kampanyanın etiketleri webhook URL’leri taşıyorsa, bunlar önceliklidir; 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"
    }
  },
  "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"
  }
}

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 amaçlıdır. Görev webhook’ları (veri olarak) geliştiriciler için burada belgelenmiştir; Task Created, Task Updated ve Task Completed etkinlikleri, diğer tüm etkinlikler gibi webhook formundaki standart etkinlik listesinde seçilebilir — bkz. Available Trigger Events ve The 22 Webhook Events.

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"
  }
}

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:

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

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:

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: etiket webhook’ları (contact_tags_updated), üç görev etkinliği ve günlük özet. Diğerleri bir kez gönderilir, bu nedenle onlar için anahtarın yapabileceği bir şey yoktur. Her etkinlik yine de X-Webhook-Delivery taşır, bu yüzden 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 #

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.