Webhook'lar ve Teslimat

Hanc.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ü.

Tüm Planlar

Yeniden denemeleri ve teslimat günlüğünü içeren çağrı sonrası teslimat, Free dahil tüm planlarda kullanılabilir.

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 → Ne zaman çalışır: Aramadan sonra ayarlı API çağrısı araç adımı
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 2xx durum 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, 429 ve 4xx de. 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 bir iş akışı API çağrısı 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.

En az bir kez

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).

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "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"
}

Alan	İçerik
`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
`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

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
`X-Correlation-Id`	Dahili izleme kimliği; destek ekibiyle iletişime geçtiğinizde bunu belirtin
`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> veya X-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ının tamamı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 bir iş akışı API çağrısı 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ı olarak 3, "urgent": "{{urgent}}" ise true olarak 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ının tamamı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 2xx ile yanıt verin; ağır işi sonra yapın.
X-Hanc-Delivery-Id değerini bir idempotency anahtarı olarak kullanın.
İsteği alamadıysanız 4xx/5xx ile yanıt verin — yeniden deneriz.
Sertifikayı geçerli tutun ve iki kaynak adresin izinli kalmasını sağlayın.

Ne gönderilir ve ne zaman​

Sunucunuza ulaşılamadığında​

Yeniden deneme zamanlaması​

Kendi zamanlamanız​

Son denemeden sonra​

Hata bildirimleri​

Teslimat günlüğü​

Ağ ve güvenlik duvarı​

İstek biçimi​

Başlıklar​

Kimlik doğrulama​

İsteği sisteminize göre biçimlendirme​

Değişkenler​

Gövde​

Yalnızca sizin alanlarınız​

Seçici gönderim​

Bir bilet sistemini bağlama​

Test​

Uç noktanız için kontrol listesi​