Webhook

Netsipp Webhook ürünü, santralde gerçekleşen çağrı olaylarını gerçekleştikleri anda sizin belirlediğiniz adrese POST eder. Bir olayı kaçırmamak için bizi sürekli sorgulamanız gerekmez; olay olduğunda biz sizi çağırırız.

Her istek tek bir olayı temsil eder ve gövdedeki scenario alanı hangi olay olduğunu söyler. Uygulamanızda yapmanız gereken ilk şey bu alana bakıp doğru işleme dallanmaktır.

İstek biçimi

Yöntem	POST
İçerik tipi	application/json
Gövde	Tek bir JSON nesnesi (dizi değil)
Beklenen yanıt	2xx

Uç noktanızın 10 saniye içinde 2xx dönmesi beklenir. Yanıt gecikirse veya 2xx dışında bir kod dönerse istek başarısız sayılır.

Yanıtı bekletmeyin

Gelen isteği hemen 2xx ile karşılayın, asıl işi kuyruğa alın. Webhook alıcısında yaptığınız uzun işlemler (veritabanı sorgusu, üçüncü parti çağrısı) çağrı akışını değil ama olay teslimini yavaşlatır.

Örnek veriler kurgusaldır

Sayfalardaki numaralar, kuyruk adları, çağrı kimlikleri ve bağlantılar gerçek trafikten alınmamıştır; biçimi göstermek için üretilmiş temsili değerlerdir. Senaryolar tek bir örnek çağrı üzerinden anlatıldığı için aynı unique_id ve santral numarası sayfalar arasında tekrar eder.

Senaryolar

Bir çağrının tipik yaşam döngüsü şu sırayla ilerler:

InboundtoPBX  →  Queue  →  Inbound_call  →  Answer  →  Hangup  →  cdr

Her senaryo ayrı bir sayfada, örnek gövdesi ve alan açıklamalarıyla birlikte anlatılıyor:

Senaryo	Ne zaman gönderilir
InboundtoPBX	Dış çağrı santrale ulaştı
Queue	Çağrı bir kuyruğa girdi
QueueLeave	Çağrı kuyruktan ayrıldı
Queue_Member_Pause	Kuyruk üyesi molaya alındı veya moladan döndü
Inbound_call	Gelen çağrı bir dahiliye yönlendirildi
Answer	Çağrı cevaplandı
Outbound_call	Dahiliden dışarı arama başlatıldı
Local_call	Dahili dahiliyi aradı
DTMF	Arayan tuşlama yaptı
Context	Çağrı bir anons veya menü adımına girdi
Hangup	Çağrı sonlandı
cdr	Çağrı kaydı özeti (ses kaydı bağlantısıyla)

Ortak alanlar

Aşağıdaki alanlar çağrı tabanlı senaryoların çoğunda aynı anlamı taşır. cdr senaryosu bu şemayı kullanmaz, kendi alan adları vardır.

Alan	Tip	Açıklama
scenario	string	Olay adı. Dallanmayı bu alana göre yapın.
pbx_num	string	Olayın gerçekleştiği santral numaranız.
unique_id	string	Çağrının benzersiz kimliği, örn. sip1-1767225600.10001. Aynı çağrıya ait olayları bu alanla eşleştirin.
customer_num	string	Karşı taraftaki abone numarası. Gelen çağrıda arayan, giden çağrıda aranan.
internal_num	string	Olaya dahil olan dahili numara.
incoming_number	string	Çağrının düştüğü numaranız (aranan numara).
timestamp	string	Olay zamanı, milisaniye cinsinden Unix epoch.

Sayısal alanlar da metin olarak gelir

talktime, holdtime, digit ve timestamp gibi alanlar JSON'da tırnak içinde, yani string olarak gönderilir. Ayrıştırırken sayıya çevirmeyi unutmayın. cdr senaryosu bunun istisnasıdır; orada sayısal alanlar gerçekten sayıdır.

unique_id ile olayları birleştirme

Tek bir çağrı için birden fazla olay alırsınız. Bunları aynı çağrıya ait saymak için unique_id alanını kullanın:

InboundtoPBX   unique_id: sip1-1767225600.10001
Queue          unique_id: sip1-1767225600.10001
Inbound_call   unique_id: sip1-1767225600.10001
Answer         unique_id: sip1-1767225600.10001
Hangup         unique_id: sip1-1767225600.10001

Queue_Member_Pause bir çağrıya değil bir agent'a ait olduğu için unique_id taşımaz. cdr ise kendi kimliğini asteriskId alanında gönderir.

Dikkat edilecekler

• Sıra garanti değildir. Olaylar ayrı ayrı gönderilir; ağ koşullarına göre Answer olayı Inbound_call olayından önce elinize geçebilir. Durumu timestamp alanına göre değerlendirin.
• Aynı olay birden fazla kez gelebilir. İşleyicinizi tekrar çalıştırıldığında yan etki üretmeyecek şekilde (idempotent) yazın; unique_id + scenario ikilisini tekrar kontrolü için kullanabilirsiniz.
• Alan listesi genişleyebilir. İleride yeni alanlar eklenebilir. Bilmediğiniz alanları yok sayın, katı şema doğrulaması yapmayın.
• Tüm alanlar her zaman gelmez. Çağrının aktığı yola göre bazı alanlar bulunmayabilir; alan okurken varlığını kontrol edin.