# 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](api-access.md) ( *Kişi Oluştur* işlemi) ve [Huniler](funnels.md) 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](api-access.md#generating-your-api-key) bölümüne bakın. Burada açıklanan **Web kancaları** sayfası yalnızca giden yön içindir.
::: note
**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:
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](#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](#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](#signed-payloads-verifying-a-webhook-really-came-from-us).
---
## 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](#webhook-reliability)), 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](../api/webhooks.md#one-subscription-for-all-client-accounts-agencies) 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](#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ı](#task-completed-webhook) 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](../api/webhooks.md) 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.
::: tip
**İpucu:** Üretim sisteminizi bağlamadan önce ham web kancası verilerini incelemek için geliştirme sırasında [webhook.site](https://webhook.site) veya [RequestBin](https://requestbin.com) 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](#signed-payloads-verifying-a-webhook-really-came-from-us) 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ı](#signed-payloads-verifying-a-webhook-really-came-from-us) 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:
```json
{
"event": "contactCreated",
"contact": { "id": "", "first_name": "Jane", "...": "..." },
"campaign": { "id": "", "name": "AI Receptionist", "status": "Live" },
"agent": { "id": "", "name": "Front Desk" },
"user": { "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 [The 22 Webhook Events](#the-22-webhook-events) bölümündedir. |
| `contact` | Etkinliğin ilgili olduğu kişi veya bir kişiye bağlı olmayan etkinlikler (örneğin `creditsRecharged`) için `null` değeri. |
| `campaign` | Kişinin ait olduğu kampanya veya kampanya yoksa `null` değeri. |
| `agent` | Görüşmeyi yöneten temsilci veya temsilci yoksa `null` değeri. |
| `user` | Verilerin sahibi olan hesap için temel kimlik bilgileri. |
> **`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](#appointment-booked-webhook)), **Yeni Mesaj** metin içeren tam bir `message` bloğu ekler (bkz. [Yeni Mesaj Webhook'u](#new-message-webhook)), **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](#deliveries-and-reads-webhook)).
> **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](../api/messages.md#send-a-message) 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:
| Görünen etiket (uygulamada) | Yükteki `event` kodu | Anlamı |
|---|---|---|
| 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 aktif gelen kutunuza geri getirir. |
| Yeni Mesaj | `new_message` | Herhangi bir kanaldaki bir görüşmeye herhangi bir mesaj eklenir — hem kişinizin 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](#new-message-webhook)). |
| Yanıtlar | `replied` | Bir kişi bir mesaja yanıt verir. |
| Okundu Bilgileri | `read` | Bir kişi bir mesajı okur (okundu bilgisini destekleyen kanallarda). Okunan mesajın kimliğini taşır — bkz. [Teslimatlar ve Okundu Bilgileri Webhook'u](#deliveries-and-reads-webhook). |
| 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 Bilgileri Webhook'u](#deliveries-and-reads-webhook). |
| İ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 (randevu alındı, potansiyel müşteri elendi vb.). |
| Randevu Alındı | `booked` | Bir kişi rezervasyon sistemi aracılığıyla bir randevu alır. |
| Kredi Harcandı | `creditsSpent` | Hesabınızdan krediler düşülür. |
| Kredi Yüklendi | `creditsRecharged` | Otomatik yükleme veya manuel satın alma yoluyla hesabınıza kredi eklenir. |
| Düşük Kredi Bakiyesi | Bir **Test** teslimatında `lowCreditBalance`, gerçek bir teslimatta `Low Credit Balance` | Kredi bakiyenizin uyarı eşiğinizin altına düştüğüne dair erken bir uyarıdır (kendi eşiğinizi belirlemediyseniz 100 kredi). Tüm alt hesapları 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 çıktığı anda yeniden 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şir. |
| Görev Tamamlandı | `taskCompleted` | Bir görev, tamamlama aşaması olarak yapılandırılmış bir aşamaya geçer. |
| 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 yaymaz. Bunun üzerine inşa etmeyin.** Bir mesajlaşma kanalı bağlanmayı tamamladığında amaçlanmış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`) içerir. 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](#contact-tags-updated-webhook) ve [Görev Tamamlandı](#task-completed-webhook).
---
## 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ı
```json
{
"event": "contactCreated",
"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": "",
"name": "AI Receptionist",
"status": "Live"
},
"agent": {
"id": "",
"name": "Front Desk"
},
"user": {
"id": "",
"email": "owner@example.com",
"first_name": "Alex",
"last_name": "Doe"
}
}
```
| Alan | Açıklama |
|---|---|
| `event` | Bu olay için her zaman `contactCreated`. |
| `contact.id` | Yeni kişinin benzersiz kimliği (ID). |
| `contact.email` / `contact.phone_number` | Biliniyorsa kişinin e-postası ve telefonu (kanala bağlı olarak 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` | Meta Click-to-WhatsApp reklam ilişkilendirmesi veya `null` — bkz. [Click-to-WhatsApp Reklam İlişkilendirmesi](click-to-whatsapp-attribution.md). |
| `campaign` | Kişinin oluşturulduğu kampanya veya `null`. |
| `agent` | Kişiye atanan temsilci veya `null`. |
| `user` | Kişinin sahibi olan hesap için temel kimlik bilgileri. |
> **"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ı
```json
{
"event": "new_message",
"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": "",
"name": "Front Desk"
},
"user": {
"id": "",
"email": "owner@example.com",
"first_name": "Alex",
"last_name": "Doe"
},
"message": {
"id": "",
"body": "Hi, are you open on Saturday?",
"direction": "inbound",
"status": "received",
"created_at": "2026-07-30T17:27:06.000Z",
"channel": "whatsapp_web"
}
}
```
| Alan | Açıklama |
|---|---|
| `event` | Bu etkinlik için her zaman `new_message`. Bunun gönderilen tam dize olduğuna dikkat edin — "Yeni Mesaj" görünen etiketi değildir. |
| `contact` | Mesajın ait olduğu görüşmenin kişisi. [Kişi Oluşturuldu](#contact-created-webhook) ile aynı şekildedir. |
| `agent` | Görüşmeyi yöneten temsilci (`id` ve `name`) veya hiçbir temsilci dahil değilse `null`. |
| `user` | Görüşmenin sahibi olan hesap için temel kimlik bilgileri. |
| `message.id` | Mesajın benzersiz kimliği. |
| `message.body` | Mesaj metni. Yalnızca bir ek (resim, sesli not, belge) taşıyan bir mesaj için boştur. |
| `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 kampanya, yayın, ş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 genellikle buraya `queued` veya `sent` olarak ulaşır ve sonrasında `delivered` değerine ulaşır — bu sonraki geçişlere ihtiyacınız varsa **Teslimatlar** ve **Okundu Bilgileri** etkinliklerini 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 Okundu Bilgileri Webhook'u](#deliveries-and-reads-webhook)). |
| `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`. |
> **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ı
```json
{
"event": "delivered",
"contact": {
"id": "",
"email": "jane@example.com",
"phone_number": "+15551234567",
"first_name": "Jane",
"last_name": "Smith",
"ad_referral": null
},
"campaign": {
"id": "",
"name": "AI Receptionist",
"status": "Live"
},
"agent": {
"id": "",
"name": "Front Desk"
},
"user": {
"id": "",
"email": "owner@example.com",
"first_name": "Alex",
"last_name": "Doe"
},
"message": {
"id": "",
"status": "delivered"
}
}
```
| Alan | Açıklama |
|---|---|
| `event` | **Teslimatlar** için `delivered` veya `undelivered`, **Okundu Bilgileri** için `read`. |
| `contact` | Mesajın gönderildiği kişi. |
| `campaign` | Kişinin ait olduğu kampanya veya `null`. |
| `agent` | Görüşmeyi 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önderme uç noktasının](../api/messages.md#send-a-message) `messageId` olarak döndürdüğü değerle ve bir [Yeni Mesaj](#new-message-webhook) 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](#new-message-webhook) 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ı
```json
{
"event": "booked",
"contact": {
"id": "",
"email": "jane@example.com",
"phone_number": "+15551234567",
"first_name": "Jane",
"last_name": "Smith"
},
"campaign": {
"id": "",
"name": "AI Receptionist",
"status": "Live"
},
"user": {
"id": "",
"email": "owner@example.com"
},
"appointment": {
"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": "",
"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`. |
| `contact` | Randevuyu alan kişi. `email` ve `phone_number` kanala bağlı olarak boş olabilir. |
| `appointment.appointment_id` | Randevunun benzersiz kimliği. |
| `appointment.start_time` / `end_time` | Randevu alınan zaman diliminin başlangıcı ve bitişi, UTC (ISO 8601) formatında. |
| `appointment.status` | Randevunun mevcut durumu. |
| `appointment.room_name` | Kullanılıyorsa, randevunun alındığı oda. |
| `appointment.description` / `summary` | Randevu ile birlikte alınan serbest metin detayları. |
| `appointment.google_calendar_event_id` | Google Takvim'in senkronize edilen etkinlik için kimliği. Randevu Alındı web kancasında 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` kimliği ile yeniden getirin ve Google Takvim bağlı olmayan hesaplarda kalıcı bir `null` bekleyin. |
| `appointment.event` | Randevu alınan 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 `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ı
```json
{
"event": "contact_tags_updated",
"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": "",
"name": "Front Desk"
},
"user": {
"email": "owner@example.com",
"first_name": "Alex",
"last_name": "Doe"
}
}
```
| Alan | Açıklama |
|---|---|
| `event` | Bu webhook için her zaman `contact_tags_updated` değerindedir. |
| `contact.id` | Etiketleri değişen kişinin benzersiz kimliği (ID). |
| `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 ilgisi için işaretlenip işaretlenmediği. |
| `contact.is_bot_active` | Yapay zeka botunun şu anda bu kişinin konuşmasında aktif olup olmadığı. |
| `contact.ad_referral` | Yalnızca kişi size ilk olarak bir Meta Tıkla-WhatsApp'a (CTWA) reklamı veya gönderisi aracılığıyla ulaştığında 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 hiçbir şey göndermez. |
| `agent` | Kişinin konuşmasını yöneten temsilci (`id` ve `name`) veya temsilci dahil değilse `null`. **15 Ağustos 2026** tarihinde eklendi. |
| `user` | Kişinin sahibi olan hesap için 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](#webhook-reliability) 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](#available-trigger-events) ve [The 22 Webhook Events](#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ı
```json
{
"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": "",
"title": "Follow up with Jane",
"description": "Confirm pricing and send proposal",
"type": "follow_up",
"priority": "high",
"stage": "",
"due_date": "2026-01-20T15:00:00Z",
"source": "ai",
"source_detail": "",
"campaign_id": "",
"linked_human_alert": "",
"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 aynı yük biçimi `taskUpdated` olarak gönderilir. |
| `contact` | Varsa, görevle bağlantılı kişi. Bağlantılı olmadığında `null`. |
| `contact.human_alert_reason` | Varsa, kişinin insan müdahalesi 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 (ID). |
| `message.due_date` | Ayarlanmışsa, görevin son teslim tarihi. |
| `message.source` | Görevi neyin oluşturduğu (`ai`, `manual`, `api`). |
| `message.source_detail` | Kaynak hakkında ek ayrıntı. |
| `message.campaign_id` | Bağlantılı kampanyanın kimliği (ID) veya `null`. |
| `message.linked_human_alert` | Varsa, bağlantılı insan uyarısının kimliği (ID). |
| `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](#webhook-reliability)), 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ı](../api/webhooks.md) ç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=` 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 `.` 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:
```js
const crypto = require("crypto");
function verify(rawBody, headers, secret) {
const timestamp = headers["x-webhook-timestamp"];
const signature = headers["x-webhook-signature"]; // "v1="
// 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:
```python
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:** 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](#webhook-reliability)) 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](#retrying-failed-deliveries) ö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ı](../api/webhooks.md) kullanın; aynı URL ile yeniden kaydetmek yeterli değildir. Destek ekibi de sizin için yeniden etkinleştirebilir.
---
## Sorun Giderme
| Sorun | Çözüm |
|---|---|
| Web kancası tetiklenmiyor | Öncelikle web kancasının satırında **kapalı** olmadığını kontrol edin. Ardından doğru etkinliklerin seçildiğinden ve URL'nizin internetten erişilebilir olduğundan emin olun. |
| Test etkinliği çalışıyor ancak gerçek etkinlikler çalışmıyor | Belirli etkinlik türünün etkinleştirildiğinden emin olun. Bir etiket uygulandığında istek bekliyorsanız, `subscribed_to_tags` öğesinin bir web kancasının etkinliklerini bir etiketle sınırlandırmadığını unutmayın; bu yalnızca hangi etiketlerin konuşma özeti bildirimi oluşturacağını daraltır. Belirli bir etiket uygulandığında istek almak için, temsilcinin (veya kampanyanın) **Etiketler** sekmesinde bir web kancası URL'si ayarlayın — bkz. [İletişim Etiketleri Güncellendi Web Kancası](#contact-tags-updated-webhook). |
| n8n / Make / Zapier'e hiçbir şey ulaşmıyor | Muhtemelen platformun "Test etkinliğini dinle" düğmesine tıkladıktan sonra yalnızca tek bir etkinliği dinleyen **Test URL'sini** kullanıyorsunuz. Canlı etkinlikler için **Üretim URL'sini** kaydedin ve iş akışını **Etkin** konuma getirin. |
| Yinelenen etkinlikler alınıyor | Aynı URL'yi işaret eden birden fazla web kancası olup olmadığını kontrol edin. **Başarısız teslimatları yeniden dene** özelliği açıksa, uç noktanız bir etkinliği kabul ettiği ancak zamanında yanıt veremediği durumlarda bir tekrar beklenir — `X-Webhook-Delivery` üzerinde tekilleştirme yapın. |
| İmza kontrolü her zaman başarısız oluyor | Neredeyse her zaman gövdenin kontrol edilmeden önce yeniden serileştirilmesinden kaynaklanır. **Ham** istek gövdesine göre doğrulayın, `.` imzalayın ve yakın zamanda değiştirdiyseniz mevcut gizli anahtarı kullandığınızdan emin olun. |
| Yeniden denemeler gerçekleşmiyor | Yeniden denemeler, o belirli web kancasında etkinleştirilmediği sürece kapalıdır. 4xx yanıtlarını yeniden denemiyoruz. |
| `campaign` bloğu her zaman `null` | Hesabınız temsilcileri kullanıyorsa bu beklenen bir durumdur: kişiler bir kampanya yerine bir temsilciyle ilişkilendirilir. Bunun yerine `agent` bloğunu okuyun — bkz. [Web Kancası Veri Formatı](#webhook-data-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. |
| Web kancası URL'si hatalar döndürüyor | URL'nizi Postman veya [webhook.site](https://webhook.site) gibi bir araçla test edin. |
| Web kancası bir kesintiden sonra tamamen tetiklenmeyi durdurdu | Tekrarlanan başarısızlıklar bir web kancasını 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 bu izni vermesini isteyin. |
| Bir web kancasının `subscribed_to_tags` listesi boş döndü | `subscribed_to_tags` bir web kancasının etkinliklerini bir etiketle sınırlandırmaz; yalnızca hangi etiketlerin konuşma özeti bildirimi oluşturacağını daraltır. Web kancası formundan düzenleme yapmak artık bu listeyi temizlemiyor (21 Temmuz 2026'da düzeltildi). Bir web kancası bu tarihten önce listesini kaybettiyse, `subscribed_to_tags` öğesini [Web Kancaları API](../api/webhooks.md) aracılığıyla tekrar ayarlayın — bkz. [Etiket Tabanlı Web Kancası Tetikleyicileri](#tag-based-webhook-triggers). |
---
## Sonraki Adımlar
- [GoHighLevel Entegrasyonu](ghl-integration.md) — Your AI Connector'ı GHL ile entegre etmek için web kancalarını kullanın.
- [API Erişimi](api-access.md) — güçlü otomasyonlar için web kancalarını API ile birleştirin.
- [Kişileri Etiketlemek İçin Etiketleri Kullanma](../get-started/creating-tags.md) — web kancalarınızı tetikleyen etiketleri ayarlayın.