Webhook v2: imzalı istekler ve otomatik yeniden deneme

Webhook v2 kullanıma açıldı. Arama, kişi, firma, anlaşma ve görev olaylarını eskisi gibi sunucunuza gönderiyor. Farkı şu: artık her istek imzalı ve başarısız bir teslimat öylece kaybolmuyor, 3 güne kadar yeniden deniyoruz. Biçim, açık bir spesifikasyon olan Standard Webhooks’a uyuyor. Kullandığınız dil için büyük ihtimalle hazır bir kütüphane vardır.

Bugün webhook’larımızı kullanıyorsanız, kullandığınız sürümün adı artık Webhook v1. 30 Kasım 2027’ye kadar çalışmaya devam ediyor, ama yeni v1 webhook oluşturulamıyor. Yeni entegrasyonlara v2 ile başlayın.

Webhook v2’de neler yeni

Her istekte 3 başlık var: webhook-id, webhook-timestamp ve webhook-signature. İmza; ID, zaman damgası ve ham gövdenin HMAC-SHA256 değeri. İmzayı kontrol ettiğinizde isteğin Hipcall’dan geldiğini, yolda kimsenin değiştirmediğini ve tekrar göndermediğini bilirsiniz.

Sunucunuz kapalıysa ya da hata döndürürse yeniden deniyoruz: yaklaşık 3 güne yayılan 10 deneme. 2xx ile başlayan her yanıt teslim edildi sayılır.

Her webhook’un bir Teslimatlar sekmesi var. Burada son 30 günün tüm olaylarını ve her olay için yaptığımız tüm denemeleri görürsünüz. Başarısız bir denemede sunucunuzun döndürdüğü yanıtı da saklıyoruz; “bu neden olmadı?” sorusunun cevabı çoğu zaman oradadır. Sorunu giderdikten sonra tek bir teslimatı ya da bir zaman aralığındaki tüm başarısız teslimatları yeniden gönderebilirsiniz.

Test olayı gönder butonu uç noktanıza imzalı bir webhook.test olayı yollar. Gerçek trafik gelmeden kodunuzu deneyebilirsiniz.

v1, teslimat durduğunda kimseye haber vermiyordu. v2 veriyor. Bir uç nokta kapanırsa ya da bir teslimatın deneme hakkı biterse, geliştirici ayarlarını yöneten kişilere e-posta gider. Webhook başına günde en fazla 1 e-posta alırsınız.

İmzalama anahtarını yenilediğinizde eski anahtar 24 saat daha geçerli kalır. Bu sürede sunucunuzu olay kaçırmadan güncelleyebilirsiniz. Anahtar sızdıysa beklemeyin, eskisini hemen iptal edin.

Bunların hepsi Ayarlar › Geliştirici › Webhooks altında, API anahtarlarınızın yanında. Her hesapta varsayılan olarak 3 webhook oluşturabilirsiniz. Daha fazlası gerekirse bize yazın.

Tüm olaylar için tek biçim

Her istek gövdesinde aynı 4 alan var:

{
  "id": "evt_2nb7kq4xyc8vfr1tlm0pzab3cd",
  "type": "call.ended",
  "timestamp": "2026-10-21T11:02:09Z",
  "data": { "...": "..." }
}

data, API’mizin o kayıt için döndürdüğü nesnenin aynısı. Webhook’ta gelen bir kişi /api/v3’ten gelen kişiyle birebir aynı görünür. API yanıtlarını zaten işliyorsanız aynı kodu kullanabilirsiniz.

contact.created ve company.created artık daha fazla yerden de gönderiliyor. v1’de yalnızca kayıt panelden oluşturulduğunda gidiyordu. v2’de API, içe aktarma, potansiyel müşteri formu ve kampanya ile oluşturulan kayıtlarda da gidiyor.

Neden v1’i güncellemedik

Standard Webhooks’un istediklerinin çoğu v1’e kimsenin entegrasyonunu bozmadan eklenebilirdi. İmza başlıkları, bir type alanı, 2xx ile başlayan her yanıtı başarılı saymak: bunların hiçbiri mevcut bir şeyi değiştirmez. Yeniden deneme ise değiştirir.

v1 her olayı bir kez gönderir. Sunucunuz hata döndürürse o olay kaybolur. v2 ise aynı olayı birden fazla kez gönderebilir. Kaydı yazan ama yanıt vermeden çöken bir sunucu düşünün. Biz bunu başarısızlık olarak görür, olayı tekrar göndeririz ve kayıt iki kez oluşur.

Kısacası teslimat garantisi “en fazla bir kez”den “en az bir kez”e geçiyor. Yeniden denemeyi v1’e sessizce ekleseydik, tekrar gelen olayı hiç beklemeyen entegrasyonlar mükerrer kayıt üretmeye başlardı ve kimse nedenini anlamazdı. Bu yüzden v2 ayrı bir webhook. Ne zaman geçeceğinize siz karar veriyorsunuz.

Sunucunuzun yapması gerekenler

1. Gövdeyi işlemeden önce imzayı doğrulayın. Resmî Standard Webhooks kütüphaneleri (Node.js, Python, PHP, Go ve diğerleri) bunu birkaç satırda yapar.
2. İşlediğiniz her olayın webhook-id değerini saklayın ve daha önce gördüğünüz bir ID gelirse atlayın. Yeniden denemeler ve elle yeniden gönderimler aynı ID’yi korur.
3. Olayların sırayla geleceğini varsaymayın. Sıralamak için timestamp alanını kullanın. Bu alan olayın gönderildiği anı değil, gerçekleştiği anı gösterir.
4. Hızlı yanıt verin. Olayı kaydeder kaydetmez 2xx döndürün, uzun işleri sonra yapın. En fazla 30 saniye bekliyoruz.
5. İnternetten erişilebilen bir HTTPS adresi kullanın. v2 başka bir yere gönderim yapmaz.

Sunucunuz yoğunsa retry-after başlığıyla 429 döndürün, gönderimi yavaşlatalım. Uç nokta kalıcı olarak kaldırıldıysa 410 döndürün, webhook’u kapatalım.

Arama kaydı bağlantıları varsayılan olarak kapalı. Her webhook için ayrı ayrı açabilirsiniz, ama yalnızca iletişim içeriğini görme izniniz varsa. API’de de kural aynı.

v1’den v2’ye geçiş

v1 ve v2 aynı anda çalışabilir, yani geçiş için bir kesinti planlamanız gerekmez:

1. Sunucunuzu imzayı doğrulayacak ve tekrar eden ID’leri atlayacak şekilde güncelleyin.
2. Ayarlar › Geliştirici › Webhooks altında bir webhook oluşturun ve v1 webhook’unuzdaki olayların aynısını seçin.
3. İkisini bir süre birlikte çalıştırıp gelenleri karşılaştırın. Bu sürede her olay size iki kez ulaşır, her sürümden bir kez. v1 isteklerinde eşleştirme yapabileceğiniz bir webhook-id olmadığı için ikisinden yalnızca birine göre işlem yapın. Geçene kadar işi v1’de bırakıp v2’yi sadece kaydetmek iyi bir yöntem.
4. v2’den emin olduğunuzda v1 webhook’unu silin.

Olay adları değişti:

Webhook v1	Webhook v2
call_init	call.initiated
call_bridged	call.connected
call_callback	call.callback_requested
call_hangup	call.ended
contact_create	contact.created
contact_number_updated	contact.number_updated
company_create	company.created
company_number_updated	company.number_updated
deal_create	deal.created
task_create	task.created

contact_custom_url_updated, company_website_url_updated ve company_custom_url_updated v2’de yok. Bu olaylar v1 ile birlikte kalkıyor.

Webhook v1 takvimi

Bugünden itibaren yeni v1 webhook oluşturamazsınız. Mevcut v1 webhook’larınız göndermeye devam eder ve onları düzenleyebilirsiniz: URL’i değiştirebilir, olayları açıp kapatabilir ya da kırık olarak işaretlenmiş bir webhook’u yeniden etkinleştirebilirsiniz.

30 Kasım 2027’ye kadar v1 ve v2 yan yana çalışır. v1 sayfalarında kapanış tarihi ve Webhook v2’ye bir bağlantı görünür.

30 Kasım 2027’de v1 göndermeyi durdurur. v1 ayarlarınızı silmiyoruz, ama o tarihten sonra hiçbir şey gönderilmez.

Marketplace’teki Slack, Telegram ve Google Chat entegrasyonları bu değişiklikten etkilenmiyor.

Nereden başlamalı

Webhook’lar, API erişimi olan paketlerde var. Ayarlar › Geliştirici › Webhooks sayfasını açın, bir webhook ekleyin ve Test olayı gönder’e basın. Sunucunuz 2xx ile yanıt verdiyse hazırsınız. API dokümantasyonu ve örnek senaryolar için geliştirici merkezine göz atın.