Webhook olayları
Rıza AL'ın izin değişikliklerini size nasıl bildirdiği: olaylar, payload, başlıklar, imza doğrulama, tekilleştirme ve yeniden deneme.
Son güncelleme:
Olaylar
Bir kişinin izni değiştiğinde Rıza AL, bağlantınızdaki webhook adresine POST isteği gönderir. Bu bildirim, İYS, onay sayfası veya panelden yapılan geri çekmeleri öğrenmenin tek yoludur.
| Olay | Ne zaman | Kime |
|---|---|---|
consent.changed | Kişinin izni değiştiğinde (İYS, Rıza AL onay sayfası, panel veya başka bir dış bağlantı kaynaklı). Her değişiklik, tür ve kanal başına ayrı bir olaydır. | Kişiyi tanıyan bağlantılar: daha önce Rıza AL'a bildirmiş olanlar veya Durum ucuyla sorgulamış (takipte) olanlar. Değişikliği başlatan bağlantı hariçtir. |
consent.reapproval_required | Gönderdiğiniz ETK ONAY kararı 3 iş gününden eski olduğunda. | Yalnızca olayı gönderen bağlantı. |
ping | Bağlantı testi sırasında. | Test edilen bağlantı. |
Payload
Payload'da kişisel veri yoktur: telefon, e-posta ve ad hiçbir zaman gönderilmez. Kişiyi externalContactId ile tanırsınız.
{
"eventId": "00000000-0000-4000-8000-000000000000",
"eventType": "consent.changed",
"occurredAt": "2026-10-13T11:00:05.000Z",
"externalCustomerId": "musteri-ornek-1",
"externalContactId": "kisi-ornek-1",
"kind": "ETK",
"channel": "MESAJ",
"decision": "RET",
"method": null,
"decidedAt": "2026-10-13T11:00:00.000Z",
"source": "IYS"
}{
"eventId": "00000000-0000-4000-8000-000000000001",
"eventType": "consent.reapproval_required",
"occurredAt": "2026-10-13T11:06:00.000Z",
"externalCustomerId": "musteri-ornek-1",
"externalContactId": "kisi-ornek-1",
"kind": "ETK",
"channel": "MESAJ",
"decision": "ONAY",
"method": "VOICE_CALL",
"decidedAt": "2026-10-08T08:00:00.000Z",
"source": "EXTERNAL",
"reason": "CONSENT_TOO_OLD_REAPPROVAL_REQUIRED"
}| Alan | Değerler / anlam |
|---|---|
eventId | UUID. X-Rizaal-Delivery başlığıyla aynıdır ve yeniden denemede sabittir. |
eventType | consent.changed, consent.reapproval_required veya ping. |
occurredAt | Rıza AL'ın olayı ürettiği an. Sıralama için kullanmayın. |
externalCustomerId | Bağlantınızdaki müşteri kimliği. |
externalContactId | Kişiyi bu bağlantıdan en son bildirirken (veya sorgularken) verdiğiniz kimlik; yoksa null. |
kind | ETK veya KVKK. |
channel | MESAJ, ARAMA veya EPOSTA (KVKK'da null). |
decision | ONAY veya RET. |
method | Onay yöntemi metni; değişikliğin kaynağına göre null olabilir. Değer kümesi sabit değildir, bilinmeyen değerleri tolere edin. |
decidedAt | Kararın verildiği an (UTC ISO). Sıralama ve uygulama için bu alan esastır. |
source | IYS, IZINLI, ADMIN_PANEL, WEB veya EXTERNAL. |
reason | Yalnızca consent.reapproval_required olayında: CONSENT_TOO_OLD_REAPPROVAL_REQUIRED. |
ping olayının gövdesi yalnızca eventId, eventType ve occurredAt alanlarını içerir.
Başlıklar
| Başlık | Anlam |
|---|---|
Content-Type | application/json |
X-Rizaal-Event | consent.changed, consent.reapproval_required veya ping. |
X-Rizaal-Delivery | Olay kimliği (UUID). Yeniden denemede sabit; tekilleştirme anahtarınızdır. |
X-Rizaal-Timestamp | Unix saniye. Her denemede yenilenir. |
X-Rizaal-Signature | v1=<hex>. Secret rotasyonu sırasında iki imza: v1=<yeni> v1=<eski>. |
İmza doğrulama
Webhook imzası, istek imzasıyla aynı yöntemle hesaplanır: HMAC-SHA256(webhookSecret, timestamp + "." + hamGövde). Kendi tarafınızda aynı değeri hesaplayıp başlıktaki değerle sabit zamanlı karşılaştırın ve zaman damgasının 300 saniyeden eski olmadığını doğrulayın.
const crypto = require("crypto");
const express = require("express");
const app = express();
// İmza HAM gövde üzerindendir: JSON ayrıştırıcıdan ÖNCE ham baytları alın.
app.post("/rizaal-webhook", express.raw({ type: "application/json", limit: "256kb" }), (req, res) => {
const ts = req.header("x-rizaal-timestamp");
const signatureHeader = req.header("x-rizaal-signature") || "";
// Tekrar saldırısına karşı 5 dakikalık tolerans.
if (!/^\d+$/.test(ts || "") || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
return res.sendStatus(401);
}
// Rotasyon penceresinde hem yeni hem eski secret kabul edilir.
const secrets = [process.env.RIZAAL_WEBHOOK_SECRET, process.env.RIZAAL_WEBHOOK_SECRET_ESKI].filter(Boolean);
const candidates = signatureHeader.split(/\s+/).filter((s) => s.startsWith("v1="));
const valid = secrets.some((secret) => {
const expected =
"v1=" + crypto.createHmac("sha256", secret).update(ts + ".", "utf8").update(req.body).digest("hex");
return candidates.some(
(c) => c.length === expected.length && crypto.timingSafeEqual(Buffer.from(c), Buffer.from(expected))
);
});
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body.toString("utf8"));
const deliveryId = req.header("x-rizaal-delivery");
// 1) deliveryId daha önce işlendiyse işlemi TEKRARLAMAYIN, yine 2xx dönün.
// 2) decidedAt'e göre uygulayın. 3) Ağır işi asenkron yapın.
res.sendStatus(200);
});Tekilleştirme ve sıralama
- Olaylar en az bir kez teslim edilir; aynı olay birden fazla gelebilir.
X-Rizaal-Deliverydeğerini ikinci kez görürseniz işlemi tekrar uygulamayın, yine de 2xx dönün. - Olaylar yeniden denemeler yüzünden sıra dışı ulaşabilir. Aynı kişi ve kanal için
decidedAtalanına göre uygulayın: kayıtlı kararınızdan eski birdecidedAtgelirse yok sayın.occurredAtve geliş sırası esas alınmaz. - Yanıtınızı hızlı verin (en çok 10 saniye) ve ağır işi asenkron yapın.
Yeniden deneme takvimi
Yalnızca 2xx yanıt başarıdır; 3xx dahil diğer her yanıt, zaman aşımı ve ağ hatası başarısız sayılır (yönlendirme izlenmez). Başarısız teslimat aşağıdaki takvimle yeniden denenir.
| Başarısız deneme | Sonraki deneme |
|---|---|
| 1. | 1 dakika sonra |
| 2. | 5 dakika sonra |
| 3. | 30 dakika sonra |
| 4. | 2 saat sonra |
| 5. | Teslimat DEAD olur; otomatik deneme durur. |
Teslimat denemeleri yaklaşık 30 saniyede bir taranır; bu yüzden ilk deneme en çok bu aralık kadar gecikebilir. Webhook adresi güvenli değilse (ör. 443 dışı port, özel IP) veya bağlantı pasifse yeniden deneme yapılmaz. Gönderim kayıtlarını panelde Hesabım → Şirket Ayarları → API Erişimi sekmesinden izleyebilir, DEAD olan teslimatları buradan yeniden gönderebilirsiniz (yalnızca DEAD kayıtlar yeniden gönderilir).
Secret rotasyonunda çift imza
Webhook secret'ı yenilendiğinde geçiş süresi boyunca Rıza AL her webhook'u hem yeni hem eski secret ile imzalar (X-Rizaal-Signature: v1=<yeni> v1=<eski>). Alıcı tarafınız ikisinden birini doğrulayabilmelidir. Aynı pencerede, Rıza AL de gelen isteklerinizde iki secret'ı kabul eder.
Alıcı tarafında önerilenler
- RET geldiğinde ilgili kişiyi o kanaldan ticari ileti/arama listelerinizden çıkarın ve bekleyen gönderimleri iptal edin.
consent.reapproval_requiredgeldiğinde kişiden yeni onay alın ve yeniexternalEventIdile gönderin; aksi halde o kanala ETK ileti göndermeyin.- Webhook kaçırma ihtimaline karşı kampanya öncesi Durum ucuyla periyodik yeniden doğrulama yapın.
- Yalnızca
ALLOWEDdurumundaki kanallardan arama/ileti yapın; Rıza AL'a ulaşamıyorsanız aramayın.
API anahtarınızı ve bağlantınızı yönetmek için panelde Hesabım → Şirket Ayarları → API Erişimi sekmesini kullanın. Hesabım sayfasını aç (giriş yapmanız gerekir).
