Webhook’lar ve REST API

Conviro, gerçek zamanlı olay bildirimleri için webhook’lar ve platformun tüm özelliklerine programatik erişim için bir REST API sunar.

Webhook’lar

Webhook Nedir?

Webhook’lar, Conviro’da belirli bir olay gerçekleştiğinde sunucunuza bir HTTP POST isteği gönderir. Böylece sürekli sorgulama (polling) yapmadan gerçek zamanlı tepki verebilirsiniz.

Kullanılabilir Olaylar

Olay	Ne Zaman Tetiklenir
`message.new`	Yeni bir mesaj gönderildiğinde (ziyaretçi veya bot tarafından)
`session.started`	Yeni bir konuşma oturumu başladığında
`session.closed`	Bir konuşma kapatıldığında
`session.escalated`	Bir konuşma yükseltildiğinde
`lead.captured`	Yeni bir lead yakalandığında
`lead.created`	Bir lead kaydı oluşturulduğunda
`lead_form.submitted`	Bir lead formu gönderildiğinde
`handoff.requested`	Bir insana devir talep edildiğinde
`csat.submitted`	Bir CSAT puanı gönderildiğinde
`csat.received`	Bir CSAT sonucu kaydedildiğinde
`ai.failed`	Yapay zekâ cevap üretemediğinde
`ticket.created`	Bir destek talebi açıldığında
`ticket.resolved`	Bir destek talebi çözüldüğünde
`contact.created`	Yeni bir kişi oluşturulduğunda
`contact.updated`	Bir kişi güncellendiğinde
`contact.merged`	İki kişi birleştirildiğinde
`contact.deleted`	Bir kişi silindiğinde

Webhook formunda ayrıca Tüm olaylar seçeneği vardır; yukarıdaki her olaya abone olur (joker * olarak saklanır) ve tek bir webhook virgülle ayrılmış olay listesi kabul eder.

Kurulum

Dashboard -> Geliştiriciler -> Webhook'lar yolunu açın.
Add Webhook’a tıklayın.
Uç nokta URL’nizi girin (HTTPS olmalıdır).
Almak istediğiniz olayları seçin.
Save’e tıklayın.

Güvenlik: HMAC-SHA256 İmzalama

Her webhook yükü, webhook secret’ınız kullanılarak HMAC-SHA256 ile imzalanır. Gerçekliğinden emin olmak için imzayı kendi sunucunuzda doğrulayın:

X-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt>          # only on a retried delivery

Özet, <unix_timestamp>.<ham_istek_gövdesi> üzerinden hesaplanır; yalnızca gövdeyi doğrulamak hiçbir zaman eşleşmez. Başlığı , ile ayırın, t= ve v1= değerlerini okuyun, webhook secret'ınızla t + '.' + rawBody için HMAC-SHA256 özetini yeniden hesaplayın ve iki özeti sabit sürede karşılaştırın. Zaman damgası birkaç dakikadan eskiyse teslimatı reddedin; böylece yakalanan bir yük tekrar oynatılamaz. Not: Kayıtlı bir webhook olmayan bir URL'ye Test gönder imzasız gider — imzalayacak bir secret yoktur; doğrulamanızı kayıtlı bir uç noktayla test edin.

Yeniden Deneme Politikası

Uç noktanız 2xx dışında bir durum kodu döndürürse Conviro, üstel geri çekilmeyle (1 dk, 5 dk, 30 dk) en fazla 3 kez yeniden dener.

REST API

Kimlik Doğrulama

Dashboard -> Geliştiriciler -> API Anahtarları -> API Anahtarı Oluştur üzerinden bir API anahtarı oluşturun.
Anahtarı Authorization başlığına ekleyin:

Authorization: Bearer sk_your_api_key_here

> Anahtar yalnızca bir kez gösterilir. Anahtar oluşturmak için en az bir kapsam (scope) seçmeniz gerekir — biri seçilene kadar Oluştur pasif kalır — ve tam sk_ değeri, Escape veya arka plana tıklamayla bilinçli olarak kapanmayan bir diyalogda tek seferliğine görünür. Sonrasında yalnızca ön ek okunabilir biçimde saklanır; gerisi bcrypt özetidir ve geri alınamaz. Diyaloğu kapatmadan önce kopyalayın. Kaybederseniz yeni bir anahtar oluşturup eskisini iptal edin.

Başlıca Uç Noktalar

Metot	Uç Nokta	Açıklama
GET	`/api/chatbots`	Tüm chatbot’ları listeler
GET	`/api/chatbots/:id`	Chatbot ayrıntılarını getirir
GET	`/api/sessions`	Oturumları listeler (filtrelerle)
GET	`/api/sessions/:id/messages`	Bir oturumun mesajlarını getirir
POST	`/api/sessions/:id/messages`	Bir oturuma mesaj gönderir
GET	`/api/contacts`	Kişileri listeler
POST	`/api/contacts`	Kişi oluşturur
GET	`/api/leads`	Potansiyel müşterileri listeler
POST	`/api/leads`	Potansiyel müşteri oluşturur
GET	`/api/analytics/overview`	Analiz özetini getirir

İstek Limitleri

Free planı: dakikada 60 istek
Starter: dakikada 120 istek
Pro: dakikada 300 istek
Growth+: dakikada 600 istek

İstek limiti başlıkları her yanıta eklenir:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200

Tam Dokümantasyon

İstek/yanıt örnekleriyle birlikte eksiksiz API referansı için /developers adresini ziyaret edin.