Webhook'lar ve Teslimat
Her görüşmeden sonra özet, döküm ve çıkarılan alanlarınız kendi sisteminize gider — erişilemediğinde yeniden denemeler, bir teslimat günlüğü ve bir şey başarısız olduğunda e-postayla.
Deneme dahil tüm planlarKendi uç noktanızHanc.AI her çağrıdan sonra çağrıyı — özet, transkript, çıkarılan alanlar — kendi sisteminize gönderebilir: bir bilet (ticket) sistemine, bir CRM'e, bir ERP'ye veya herhangi bir HTTPS uç noktasına. Bu sayfa, bu teslimatın tam olarak nasıl davrandığını açıklar: sunucunuza ulaşılamadığında ne olduğunu, ne sıklıkla yeniden denediğimizi, güvenlik duvarınızın neye izin vermesi gerektiğini ve isteğin nasıl göründüğünü.
Yeniden denemeleri ve teslimat günlüğünü içeren çağrı sonrası teslimat, ücretsiz deneme dahil her planda kullanılabilir.
Neler yapabilirsiniz
- Her görüşmeyi sisteminize gönderin — görüşme ve analizi bittiğinde bir destek talebi sistemine, CRM'e, ERP'ye veya herhangi bir HTTPS uç noktasına.
- İsteği şekillendirin — görüşmeden gelen değişkenlerle doldurulan kendi JSON gövdeniz, başlıklarınız ve sorgu parametreleriniz.
- Yalnızca bazı görüşmeleri gönderin — sade bir dille yazılan bir koşul, hangi görüşmelerin isteği tetikleyeceğine karar verir.
- Hiçbir görüşmeyi kaybetmeyin — başarısız teslimatlar yaklaşık 3,4 gün boyunca yeniden denenir, günlüğe kaydedilir ve yeniden gönderilebilir.
- Hatalardan haberdar olun — bir istek teslim edilmediğinde e-posta.
Nasıl kurulur
- Görüşme sonrası bir API çağrısı ekleyin
Ajanı açın → Eylemler → Araç Ekle → Aramadan sonra → API çağrısı. Bir iş akışında bunun yerine API çağrısı ve Ne zaman çalışır: Aramadan sonra ile bir Araç düğümü kullanın.
- İsteği tanımlayın
Bir ad, isteğe bağlı bir koşul, uç noktanızın URL'sini ve HTTP yöntemini girin. Uç noktanızın bizi tanıması için gereken başlıkları ekleyin (bkz. Kimlik doğrulama) ve sisteminiz kendi yapısını bekliyorsa değişkenlerle Gövde (JSON) ekleyin (bkz. İsteği şekillendirme).

- Yeniden denemeleri ve hata e-postasını ayarlayın
Varsayılan zamanlamayı koruyun veya Hata durumunda yeniden denemeler altında kendinizinkini ayarlayın ve Hata bildirimi altında kimin e-posta alacağını seçin.

- Test edin
API Yapılandırmasını Test Et'e basın, ardından bir test görüşmesi yapın. Bkz. Test etme.
Örnek senaryolar
Her arıza bildirimi için bir talep Arayan bozuk bir modem bildirir → ajan müşteri numarası, talep kategorisi ve öncelik alanlarınızı doldurur → görüşmeden sonra destek talebi sisteminiz, Yalnızca benim alanlarımı gönder açıkken kendi yapısında bir talep alır.
Yalnızca önemli görüşmeler "Yalnızca arayan bir arıza bildirirse" koşulu sağlanır → istek destek sisteminize gider; diğer görüşmeler hiçbir yere ya da CRM'inize yönelik ikinci bir eyleme gider.
Sunucunuz hafta sonu kapalıydı İlk denemeler başarısız olur → istek zamanlamaya göre yeniden denenir → sunucunuz geri geldiğinde görüşme kendiliğinden ulaşır; zamanlama biterse bir e-posta alırsınız ve teslimat günlüğünden yeniden gönderebilirsiniz.
Ne gönderilir ve ne zaman
İstek, çağrı sona erip analizi tamamlandığında (özet, duygu durumu, çıkarılan alanlarınız) gönderilir — genellikle çağrı kapandıktan birkaç saniye sonra.
| Kaynak | Nerede ayarlanır |
|---|---|
| API Çağrısı eylemi | Ajan → İşlemler → Post call → API Çağrısı |
| İş akışı adımı | İş akışı oluşturucu → Araç düğümü (Araç yapılandır penceresi) → Ne zaman çalışır: Aramadan sonra ayarlı API çağrısı. Bkz. İş akışları → Araç |
| Ajan webhook'u | Ajanın webhook_url alanı (API referansı) |
Bir ajanın görüşme sırasında yaptığı istekler (canlı araçlar) bu sayfanın kapsamında değildir: bunlara tam o anda ihtiyaç duyulur ve sonradan asla tekrarlanmazlar.
Sunucunuza ulaşılamadığında
Hiçbir şey kaybolmaz. İstek, ilk denemeden önce bir teslimat kuyruğuna kaydedilir ve sunucunuz onu kabul edene ya da zamanlama sona erene kadar orada kalır.
- Uç noktanız 30 saniye içinde herhangi bir
2xxdurum koduyla yanıt verirse teslimat başarılı sayılır. - Diğer her şey yeniden denenir: reddedilen bağlantı, DNS veya TLS hataları, zaman aşımı ve diğer tüm durum kodları —
5xx,429ve4xxde. Bir API anahtarının süresi dolduysa ve onu yenilerseniz, bekleyen çağrılar kendiliğinden ulaşır. - Her deneme, aynı teslimat kimliğiyle aynı isteği gönderir.
Yeniden deneme zamanlaması
| Deneme | Öncesindeki bekleme | Çağrı bittikten sonra geçen süre |
|---|---|---|
| 1 | — (hemen) | ~0 |
| 2 | 1 dakika | ~1 dk |
| 3 | 5 dakika | ~6 dk |
| 4 | 30 dakika | ~36 dk |
| 5 | 2 saat | ~2 sa 36 dk |
| 6 | 6 saat | ~8 sa 36 dk |
| 7 | 24 saat | ~1 gün 8 sa |
| 8 | 48 saat | ~3 gün 8 sa |
Bu, yaklaşık 3,4 güne yayılan 8 deneme demektir — hafta sonu boyunca süren bir kesintiyi karşılamaya yeter.
Kendi zamanlamanız
Bir API Çağrısı eyleminde (ve çağrıdan sonra çalışan, API çağrısı seçili bir iş akışı Araç adımında) zamanlamayı Hata durumunda yeniden denemeler altında değiştirebilirsiniz:
- en fazla 10 yeniden deneme,
- her bekleme 1 dakika ile 7 gün arasında,
- tüm satırları kaldırırsanız istek, yeniden deneme olmadan bir kez gönderilir.
Hiç dokunmadığınız bir eylem, yukarıdaki varsayılan zamanlamayı izler.
Son denemeden sonra
Teslimat Teslim edilemedi olarak işaretlenir, bu ayarı kapatmadıysanız e-postayla bilgilendirilirsiniz ve istek 30 gün boyunca saklanır. Bu süre içinde isteği yeniden gönderebilirsiniz — teslimat günlüğünde tek bir tıklamayla veya tek bir API çağrısıyla. Yeniden gönderme, zaten başarılı olmuş bir teslimat için de mümkündür; örneğin sizin tarafınızda yapılan bir geri yüklemeden sonra.
Herhangi bir webhook'tan bağımsız olarak çağrının kendisi Hanc.AI hesabınızda kalır — transkript, özet, kayıt ve çıkarılan alanlar Aramalar bölümünde ve API üzerinden erişilebilir durumdadır. Uzun bir kesinti, sisteminize aktarımı geciktirir; görüşmeyi silmez.
Teslimat en az bir kez gerçekleşir. Nadir durumlarda — örneğin sunucunuz bir isteği işlediği hâlde yanıt bize zamanında ulaşmadığında — aynı çağrı iki kez gelir. Bir tekrarı tanıyıp atlamak için X-Hanc-Delivery-Id değerini kullanın.
Hata bildirimleri
Günlüğü izlemek zorunda değilsiniz: bir eylem, isteği teslim edilmediğinde size e-postayla haber verebilir. Eylemde (veya iş akışı adımında) Hata bildirimi altında seçim yapın:
| Ayar | E-posta ne zaman gönderilir |
|---|---|
| Son denemeden sonra (varsayılan) | Bir kez; yeniden deneme zamanlaması tükendiğinde ve istek Teslim edilemedi olarak işaretlendiğinde |
| Her başarısız denemeden sonra | Her başarısız denemeden sonra, bir sonraki denemenin zamanıyla birlikte — ve son denemeden sonra |
| Bildirme | Hiçbir zaman; hatalar yalnızca günlükte görünür |
E-posta; eylemi ve ajanı, sunucunuzun ana makine adını, sunucunun ne yanıt verdiğini (örneğin HTTP 503 veya timeout after 30s) ve bunun kaç denemeden kaçıncısı olduğunu belirtir, ayrıca teslimat günlüğüne bağlantı verir. Son e-posta, isteğin ne zamana kadar saklandığını ve yeniden gönderilebileceğini de bildirir.
Alıcı alanı, e-postanın kime gideceğini belirler — genellikle alıcı sistemi işleten kişidir. Boş bırakılırsa e-posta hesap sahibine gider. E-posta, hesabın dilinde yazılır.
Bir kesintinin gelen kutunuzu doldurmaması için bildirimler eylem başına saatte 10 ve günde 30 ile sınırlıdır; bir duraklamadan önceki son bildirim, duraklamanın ne zamana kadar süreceğini belirtir. Her hata yine de günlüğe kaydedilir. Elle yeniden gönderdiğiniz bir istek için bildirim gönderilmez.
Teslimat günlüğü
Her deneme kaydedilir: zaman, HTTP durum kodu veya ağ hatası, süre ve sunucunuzun yanıtının başlangıcı.
Uygulamada: CRM → İletişimler → API çağrısı türündeki bir kaydı açın. Durumu (Teslim edildi, Yeniden deneniyor, Teslim edilemedi), tüm denemeleri, bir sonraki denemenin zamanını ve Yeniden gönder düğmesini görürsünüz.
API üzerinden (kimlik doğrulama, x-api-key başlığındaki API anahtarınızla yapılır):
| İstek | Sonuç |
|---|---|
GET /v1/webhook-deliveries | Teslimatlarınız, en yenisi en üstte. Filtreler: status (pending, delivered, failed), agent_id, call_id, limit, offset |
GET /v1/webhook-deliveries/{id} | Tüm denemeleri ve istek gövdesiyle birlikte tek bir teslimat |
POST /v1/webhook-deliveries/{id}/resend | Teslimatı hemen yeniden gönderir ve sonucu döndürür |
{
"id": "6ac71fb82e4f72e709a4a566",
"delivery_id": "0b0f2f0e-6c0f-4f0b-9c55-3c6a3a1f8a11",
"kind": "api_call",
"name": "Create ticket",
"call_id": "6ac71f9d2e4f72e709a4a4f0",
"status": "pending",
"attempts_made": 2,
"attempts_max": 8,
"next_attempt_at": "2026-10-09T11:36:04.000Z",
"attempts": [
{ "n": 1, "at": "2026-10-09T11:30:03.512Z", "duration_ms": 212, "error": "connection refused" },
{ "n": 2, "at": "2026-10-09T11:31:04.007Z", "duration_ms": 187, "status_code": 503, "error": "HTTP 503", "response_preview": "Service Unavailable" }
]
}
Saklanan isteğin başlık değerleri (anahtarlarınız) hiçbir zaman döndürülmez.
Ağ ve güvenlik duvarı
Hanc.AI sizin uç noktanızı çağırır — bağlantı her zaman bizim tarafımızdan sizin tarafınıza doğru açılır.
| Yön | Hanc.AI'den giden → sizin tarafınızda gelen |
| Kaynak IP adresleri | 178.104.10.47 (teslimat hizmeti) ve 128.140.65.92 (çağrı hizmeti, yedek yol olarak kullanılır) |
| Protokol | HTTPS (TLS 1.2 veya daha yenisi). Şifrelenmemiş HTTP çalışır, ancak önerilmez |
| Port | 443 veya URL'nizde belirtilen port |
| IP sürümü | IPv4 |
| Sertifika | Geçerli olmalı ve genel bir sertifika yetkilisi tarafından verilmiş olmalıdır; kendinden imzalı sertifikalar reddedilir |
| Yanıt süresi | 30 saniye içinde yanıt verin — en iyisi hemen onaylayıp arka planda işlemektir |
| Yönlendirmeler | İzlenir, en fazla 5 |
İzin listesi: Güvenlik duvarınız veya WAF'ınız kaynak adrese göre filtreleme yapıyorsa, webhook yolunuz için yukarıdaki iki adrese izin verin. Bu adreslerdeki bir değişikliği önceden duyururuz.
Mümkün değil: özel bir ağın içindeki adresler (10.x, 172.16–31.x, 192.168.x, localhost). Uç nokta internetten erişilebilir olmalıdır — doğrudan veya ters proxy'niz / API ağ geçidiniz üzerinden.
Tarayıcı: Webhook'lar sunucudan sunucuya çalışır. Tarayıcı ayarları, uzantılar veya çalışanların bilgisayarlarındaki açık portlar bu sürece dahil değildir.
İstek biçimi
POST, PUT ve PATCH bir JSON gövdesi taşır (Content-Type: application/json, UTF-8).
{
"id": "6ac7ea6eca60c6024b465c70",
"agent_id": "6ac2a93e36bad261cf088684",
"call_from": "+431234567890",
"call_to": "+439876543210",
"direction": "inbound",
"call_type": "phone",
"call_status": "success",
"start_timestamp": 1730000000000,
"end_timestamp": 1730000187000,
"duration": 187000,
"call_summary": "Customer reports a broken router and asks for a callback…",
"transcription": [
{ "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
{ "speaker": "user", "content": "Hi…", "timestamp": 1730000003000 }
],
"task_achieved": true,
"sentiment": { "sentiment": "neutral", "explanation": "…" },
"custom_analysis_data": {
"customer_number": "K-20417",
"ticket_category": "Hardware",
"priority": "high"
},
"collected_data": { },
"transfer_history": [ ],
"recording_url": "https://…",
"disconnection_reason": "user_hangup",
"is_anonymous": false,
"is_simulation": false,
"created_at": 1730000000000,
"updated_at": 1730000187000
}
| Alan | İçerik |
|---|---|
id, agent_id | Çağrı ve onu yürüten ajan |
call_summary | Görüşmenin özeti |
transcription | Görüşmenin tamamı; konuşma sırasıyla ve zaman damgalarıyla |
call_from, call_to, direction | Arayan, aranan numara, gelen veya giden |
call_type, call_status | phone veya web; success veya failed |
start_timestamp, end_timestamp, duration | Unix zamanı ve milisaniye cinsinden süre |
custom_analysis_data | Görüşmeden çıkarılan kendi alanlarınız — bkz. Veri Alma Değişkenleri |
collected_data | Ajanın çağrı sırasında topladığı veriler |
sentiment, task_achieved | Görüşmenin duygu durumu ve hedefine ulaşılıp ulaşılmadığı |
recording_url | Kayıt açıksa, kaydın bağlantısı |
transfer_history | Çağrı sırasında gerçekleşen aktarımlar |
disconnection_reason | Çağrının nasıl sona erdiği, örneğin user_hangup, agent_hangup, call_transfer, voicemail |
is_anonymous, is_simulation | Arayan numarasını gizledi; çağrı simüle edilmiş bir testti |
created_at, updated_at | Çağrı kaydının sistemde oluşturulduğu ve en son güncellendiği zaman (Unix zamanı, ms) |
Yalnızca bu alanlar gönderilir. Çağrıyla ilgili başka hiçbir şey platformun dışına çıkmaz.
GET ve DELETE için aynı alanlar sorgu dizesinde taşınır; transcription gibi iç içe değerler gönderilmez.
Başlıklar
| Başlık | Anlamı |
|---|---|
X-Hanc-Delivery-Id | Teslimatı tanımlar. Her denemede aynıdır — yinelenenleri atlamak için kullanın |
X-Hanc-Attempt | Denemenin numarası, 1 ile başlar |
User-Agent | HANC-Webhooks/1.0 |
| sizin başlıklarınız | Eylemde yapılandırdığınız her şey |
Kimlik doğrulama
Uç noktanızın bizi nasıl tanıyacağına siz karar verirsiniz:
- API anahtarı veya token — eyleme bir başlık ekleyin, örn.
Authorization: Bearer <token>veyaX-API-Key: <key>. Başlıklar her denemeyle birlikte gönderilir. - Basic auth —
Authorization: Basic <base64(user:password)>. - Sorgu parametresi — anahtarı URL'de bekleyen sistemler için.
- Kaynak adres — yalnızca yukarıda listelenen IP adreslerine izin verin.
Yöntemler birleştirilebilir; olağan kurulum, bir anahtar ile IP izin listesinin birlikte kullanılmasıdır.
İsteği sisteminize göre biçimlendirme
Varsayılan olarak istek çağrı alanlarını taşır (bkz. İstek biçimi). Kendi yapısını bekleyen bir sistem için — bilet sistemlerinin çoğu böyledir — bu yapıyı kendiniz tanımlar ve çağrıdaki verilerle doldurursunuz.
Değişkenler
Çağrı sonrası bir API Çağrısı eyleminde ve API çağrısı seçili bir iş akışı Araç adımında URL, başlıklar, sorgu parametreleri ve gövde, çift süslü parantez içinde değişken alır. Bu değişkenler, istek gönderilmeden hemen önce çağrıdaki verilerle doldurulur.
| Değişken | Değer |
|---|---|
{{call_id}} | Çağrının kimliği |
{{call_from}}, {{call_to}} | Arayan ve aranan numara |
{{customer_phone}}, {{customer_email}} | Çağrının yönü ne olursa olsun, karşı tarafın numarası ve e-posta adresi |
{{call_direction}}, {{call_type}} | inbound / outbound, phone / web |
{{call_start}}, {{call_end}} | Başlangıç ve bitiş, ISO 8601 (UTC) |
{{call_duration}} | Saniye cinsinden süre |
{{call_summary}} | Görüşmenin özeti |
{{call_transcription}} | Görüşmenin tamamı, metin olarak |
{{call_sentiment}}, {{call_task_achieved}} | Duygu durumu ve hedefe ulaşılıp ulaşılmadığı |
{{call_recording_url}} | Kaydın bağlantısı |
{{agent_id}} | Ajanın kimliği |
| kendi alanlarınız | Adıyla kullanılan her Veri Alma Değişkeni, örn. {{customer_number}}, {{priority}} — ve bir iş akışının çağrı sırasında topladığı her değişken |
Bilinmesi gereken kurallar:
- Yalnızca tek bir değişkenden oluşan bir gövde alanı, o değişkenin türünü korur:
"priority": "{{priority}}"sayı olarak3,"urgent": "{{urgent}}"isetrueolarak gönderilir. Değişkenin çevresinde metin varsa değer metne dönüşür. - URL'ye yerleştirilen bir değer otomatik olarak yüzde kodlamasıyla kodlanır (
+43…,%2B43…olur). - Çağrıda değeri olmayan bir değişken boş gönderilir — asla olduğu gibi
{{name}}biçiminde gönderilmez.
Uygulamada, bir alandaki {x} düğmesi kullanılabilir değişkenleri listeler; gövdede {{ yazdığınızda değişkenler önerilir.
Gövde
Eylemdeki Gövde (JSON) alanına, sisteminizin beklediği JSON nesnesini gerektiği kadar derin iç içe yapıda yazarsınız:
{
"ticket": {
"subject": "Call from {{customer_phone}}: {{ticket_category}}",
"comment": { "body": "{{call_summary}}" },
"priority": "{{priority}}",
"custom_fields": [
{ "id": 360001, "value": "{{customer_number}}" },
{ "id": 360002, "value": "{{call_recording_url}}" }
],
"tags": ["phone-agent"]
}
}
Yalnızca sizin alanlarınız
Yalnızca benim alanlarımı gönder açıkken istek yalnızca gövdenizi ve sorgu parametrelerinizi taşır — çağrı verileri eklenmez. Kapalı bırakırsanız alanlarınız çağrı alanlarıyla birlikte gönderilir.
Seçici gönderim
Gündelik dille yazılmış bir koşul (“yalnızca arayan bir arıza bildirirse”), hangi çağrıların isteği tetikleyeceğini belirler. Birden fazla eylem, farklı sistemlere veya uç noktalara yönlendirilebilir.
Bir bilet sistemini bağlama
HTTP API'si veya gelen webhook'u olan her bilet sistemi çağrıları alabilir — doğrudan, arada başka bir yazılım olmadan. Sizin tarafınızda gerekenler:
- İnternetten HTTPS üzerinden erişilebilen ve JSON kabul eden bir uç nokta.
- Bu uç nokta için, eyleme başlık olarak girilen bir kimlik bilgisi (API anahtarı, token veya basic auth).
- Adrese göre filtreleme yapıyorsanız — izin listenizde yukarıdaki iki IP adresi.
Ardından eylemde:
- Alanlarınızı tanımlayın. Müşteri numarası, bilet kategorisi, öncelik, geri arama istendi gibi Veri Alma Değişkenleri ekleyin. Ajan bunları görüşmeden doldurur.
- Gövdeyi bilet API'nizin yapısına uygun biçimde yazın ve değişkenleri ait oldukları yerlere yerleştirin.
- Yalnızca benim alanlarımı gönder seçeneğini açın.
- API Yapılandırmasını Test Et düğmesine basın, ardından bir test çağrısı yapın.
Sisteminiz için gövdeyi sizinle birlikte hazırlamaktan memnuniyet duyarız.
Test
Bağlantı testi. Eylemdeki API Yapılandırmasını Test Et düğmesi hemen bir örnek istek gönderir ve uç noktanıza ulaşılıp ulaşılmadığını gösterir.
Yeniden deneme testi — mekanizmayı kendi gözlerinizle görmek için:
- Eylemde Hata durumunda yeniden denemeler altında kısa bir zamanlama ayarlayın; örneğin 1'er dakikalık üç bekleme.
- Uç noktanızı durdurun veya adreslerimizi güvenlik duvarında engelleyin.
- Ajana bir test çağrısı yapın.
- CRM → İletişimler bölümünü açın: kayıtta Yeniden deneniyor durumu, başarısız deneme ile hatası ve bir sonraki denemenin zamanı görünür.
- Uç noktayı yeniden başlatın (veya engeli kaldırın). Bir sonraki deneme çağrıyı teslim eder ve kayıt Teslim edildi durumuna geçer — ya da hemen teslim etmek için Yeniden gönder düğmesine basın.
Uç noktanız için kontrol listesi
- İstek kaydedilir kaydedilmez
2xxile yanıt verin; ağır işi sonra yapın. X-Hanc-Delivery-Iddeğerini bir idempotency anahtarı olarak kullanın.- İsteği alamadıysanız
4xx/5xxile yanıt verin — yeniden deneriz. - Sertifikayı geçerli tutun ve iki kaynak adresin izinli kalmasını sağlayın.
Benzer entegrasyonlar
Teslimatları ve görüşmeleri HANC API üzerinden okuyun.
Ajanlarınıza görüşme sırasında kendi araçlarınızı verin.
Kendi anahtarınızla monday.com, GoHighLevel, Kommo ve CallRail.