Webhook'lar

RolChat olayları sistemlerinize imzalı HTTP POST istekleri olarak iletir. Bu sayfa eklenti webhook’larını anlatır; bir Otomasyon kuralının gönderdiği webhook’lar yeniden denemeler, bekleme süresi ve gizli anahtar değişimi bakımından farklıdır, bkz. Otomasyon webhook’ları. Aynı kurallar ters yönde de geçerlidir: sisteminiz, bir eklenti veya bir sağlayıcı RolChat’e veri gönderdiğinde. Her teslimatı, üzerinde işlem yapmadan önce aşağıdaki sırayla doğrulayın.

Bir teslimat nasıl görünür

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: RolChat-Webhook/1.0
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=a1b2c3…
X-RolChat-Nonce: nonce_01HKQN9…
X-RolChat-Event-Id: evt_01HKQN9…

{ "id": "evt_01HKQN9…", "type": "conversation.created", "occurred_at": "…", "data": { … } }

Başlık	Anlamı
`X-RolChat-Timestamp`	Gönderim anındaki Unix saniyeleri. İmzalanan mesajın parçasıdır.
`X-RolChat-Signature`	`sha256=<hex>`. Önek algoritmayı belirtir, böylece ileride değiştirilebilir.
`X-RolChat-Nonce`	Bu HTTP isteğine özgü bir ULID. Yeniden deneme yeni bir nonce alır.
`X-RolChat-Event-Id`	Olayın kendi kimliği. Yeniden denemelerde değişmez; tekilleştirme için kullanın.

Giden teslimatlar yalnızca HTTPS endpoint’lerine gider. Abonelik oluşturulurken bir HTTP URL’si reddedilir.

İmza

İmzalanan mesaj; zaman damgası, bir nokta karakteri ve ham istek gövdesinin bayt bayt kendisidir:

canonical = "<timestamp>.<body>"
signature = hex( HMAC-SHA256( secret, canonical ) )

Ayrıştırılmış JSON’un yeniden serileştirilmiş bir kopyasını değil, aldığınız baytları imzalayın. Boşluk veya anahtar sırası değişiklikleri imzayı bozar. Kabul edilen tek algoritma SHA-256’dır.

Otomasyon modülünün HTTP eylemiyle gönderilen istekler iki başlıkla imzalanır. X-RolChat-Signature, sha256= artı yalnızca gövdenin HMAC-SHA256 değeridir. X-RolChat-Signature-V2, <timestamp>.<body> değerinin HMAC-SHA256 karşılığıdır; bu, yukarıda anlatılan şemadır ve zaman damgası olarak X-RolChat-Timestamp kullanılır. V2 başlığını doğrulayın; yalnızca gövdeyi imzalayan başlık, yeniden oynatılan bir isteğe karşı koruma sağlamaz. Bu istekler X-RolChat-Nonce ve X-RolChat-Event-Id taşımaz; bir teslimatın tüm denemeleri aynı X-RolChat-Delivery-Id değerini ve X-RolChat-Attempt içinde kendi numarasını taşır, bu yüzden nonce kontrolünü atlayın ve X-RolChat-Delivery-Id değerine göre tekilleştirin. Doğrulama örnekleri X-RolChat-Signature başlığını okur: otomasyon istekleri için bunun yerine X-RolChat-Signature-V2 okuyun.

Bir teslimatı doğrulama

Bu beş kontrolü sırayla yapın. Python, Node.js, Go, Ruby ve PHP örnekleri doğrulama örnekleri sayfasındadır.

Güncellik. |now − X-RolChat-Timestamp| > 300 saniye ise reddedin (400). Beş dakika saat kaymasını tolere eder ve ele geçirilmiş bir isteği bu süreden sonra değersiz kılar. Sunucunuzu NTP ile senkron tutun.
İmza. Beklenen değeri hesaplayın ve sabit zamanlı bir karşılaştırmayla karşılaştırın (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Uyuşmazlıkta 401 ile reddedin. Düz bir dize karşılaştırması zamanlama bilgisi sızdırır ve kabul edilemez.
Nonce. X-RolChat-Nonce değerini, atomik bir yoksa-ayarla işlemiyle (SET NX EX 600) 10 dakikalık TTL ile saklayın. Zaten varsa 409 ile reddedin: istek bir tekrardır. Nonce deponuz çalışmıyorsa, RolChat’in yeniden denemesi için 503 ile güvenli şekilde başarısız olun; asla “kabul et” durumuna düşmeyin.
Gövdeyi ancak şimdi ayrıştırın.
Olay kimliğine göre tekilleştirin. Yeniden denemeler yeni bir nonce ama aynı X-RolChat-Event-Id değerini taşır. O kimliği son yedi gün içinde işlediyseniz, yeniden işlemeden 200 yanıtı verin.

Teslimat güvenle kabul edilir edilmez 2xx yanıtı verin; işi eşzamansız yapın. RolChat bir yanıt için 15 saniye bekler.

Gizli anahtarlar

Bir webhook gizli anahtarı, base64url ile kodlanmış 64 rastgele bayttır (yaklaşık 86 karakter). Abonelik veya eklenti oluşturulduğunda üretilir ve bir kez gösterilir.
Kendi kasanızda veya ortam değişkenlerinizde saklayın; RolChat yalnızca şifrelenmiş bir kopya tutar.
90 günden sonra döndürme önerilir; ürün bir hatırlatma gösterir ama döndürülmediği için bir aboneliği asla devre dışı bırakmaz.
Döndürme bir örtüşme penceresi kullanır: POST /api/v1/plugins/{id}/webhook-secret/rotate sonrasında hem eski hem yeni anahtar yedi gün boyunca doğrulamadan geçer, yeni teslimatlar yenisiyle imzalanır ve eskisi pencereden sonra silinir. Döndürdüğünüz anda hiçbir şey bozulmaz.
Bir gizli anahtar sızarsa POST /api/v1/plugins/{id}/webhook-secret/revoke onu hemen geçersiz kılar, yenisini üretir, hesap yöneticilerine e-posta gönderir ve bir denetim kaydı yazar.

Yeniden denemeler ve dead letter’lar

2xx dışındaki bir yanıt veya bir ağ hatası yeniden denemeyi zamanlar:

Deneme	Öncekinden sonraki gecikme
1	hemen
2	15 saniye
3	1 dakika
4	5 dakika
5	30 dakika
6	2 saat
7	8 saat
8	24 saat

408, 429, 5xx ve ağ hataları yeniden denenir. 400, 401, 403, 404 ve 410 denenmez: teslimat doğrudan dead-letter kuyruğuna gider, çünkü reddedilmiş bir imzayı veya var olmayan bir endpoint’i yeniden denemek işe yaramaz. Sekiz başarısız denemeden sonra teslimat yine dead-letter kuyruğuna alınır.

Dead letter’lar 30 gün saklanır ve Ayarlar → Eklentiler → {plugin} → Webhook kaydı → DLQ bölümünde görünür; burada bir yönetici birini yeniden oynatabilir (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Sınırlar

Giden gövde: varsayılan 1 MB (eklenti başına yapılandırılabilir). RolChat’e gelen gövde: 5 MB. Daha büyüğü 413 alır.
Bir eklenti allowed_source_ips tanımlayabilir; RolChat bu izin listesini doğrulamadan önce uygular.
Ek bir mantık kontrolü olarak RolChat-Webhook/1.0 user agent’ını kontrol edebilirsiniz. Bu bir güvenlik önlemi değildir.

RolChat’e gelen webhook’lar

Sağlayıcılar kendi imza şemalarını (Twilio, Telnyx, Bandwidth, WhatsApp için Meta, Stripe) kullanarak RolChat’e /api/v1/webhooks/{category}/{adapter} adresinden gönderim yapar. Her adaptör kendi sağlayıcısının imzasını doğrular, payload’u normalleştirir ve bir RolChat imzasıyla dahili olay veri yoluna yeniden yayınlar. Kendi sisteminiz, yukarıda açıklanan aynı X-RolChat-* başlıklarıyla, endpoint’in ait olduğu eklentinin gizli anahtarıyla imzalayarak RolChat’e gönderim yapabilir.

Otomasyon webhook’ları

Otomasyon modülünün HTTP isteği gönder eyleminin kendi teslimat kuralları vardır:

Hesap başına tek gizli anahtar. Otomasyon ekranında gösterin veya değiştirin (Owner ve Admin). Değişim hemen geçerli olur: çakışma penceresi yoktur, eski anahtar anında doğrulanmayı bırakır; bu yüzden önce alıcınızı güncelleyin veya kısa bir boşluğu kabul edin.
Bekleme süresi: RolChat yanıt için 10 saniye bekler.
Yeniden denemeler: toplamda en fazla 6 deneme. 2. denemeden önceki bekleme 30 saniyedir, ardından yaklaşık 2 dakika, 8 dakika, 32 dakika ve 2 saat 8 dakika; her biri en fazla %20 değişir. Tek bir bekleme asla 6 saati aşmaz.
Neler yeniden denenir: ağ hataları, zaman aşımları, 5xx, 408, 425 ve 429. Diğer 4xx yanıtları, engellenmiş bir adres veya aşırı büyük bir gövde yeniden denenmez: teslimat, son başarısız denemeden sonra olduğu gibi doğrudan dead-letter kuyruğuna gider.
Başlıklar: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Alıcınızı test etme

POST /api/v1/webhooks/test-signature, çağıran eklentinin endpoint’ine sentetik, imzalı bir olay gönderir; böylece gerçek trafik gelmeden önce uygulamanızı uçtan uca doğrulayabilirsiniz.

Yaygın hatalar

Ham baytlar yerine ayrıştırılıp yeniden kodlanmış JSON’a karşı doğrulama yapmak.
İmzaları karşılaştırmak için == kullanmak.
Olay kimliği yerine nonce’a göre tekilleştirmek (her yeniden denemede yeni bir nonce vardır).
Beş dakikadan fazla kaymış bir saat.
Yanıt vermeden önce yavaş işler yapmak, ardından 15 saniyede zaman aşımına uğrayıp aynı olayı yeniden almak.