İçeriğe geç

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.

Webhook olay türleri (eventType)
OlayNe zamanKime
consent.changedKiş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_requiredGönderdiğiniz ETK ONAY kararı 3 iş gününden eski olduğunda.Yalnızca olayı gönderen bağlantı.
pingBağ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.

consent.changedjson
{
  "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"
}
consent.reapproval_requiredjson
{
  "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"
}
Payload alanları
AlanDeğerler / anlam
eventIdUUID. X-Rizaal-Delivery başlığıyla aynıdır ve yeniden denemede sabittir.
eventTypeconsent.changed, consent.reapproval_required veya ping.
occurredAtRıza AL'ın olayı ürettiği an. Sıralama için kullanmayın.
externalCustomerIdBağlantınızdaki müşteri kimliği.
externalContactIdKişiyi bu bağlantıdan en son bildirirken (veya sorgularken) verdiğiniz kimlik; yoksa null.
kindETK veya KVKK.
channelMESAJ, ARAMA veya EPOSTA (KVKK'da null).
decisionONAY veya RET.
methodOnay 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.
decidedAtKararın verildiği an (UTC ISO). Sıralama ve uygulama için bu alan esastır.
sourceIYS, IZINLI, ADMIN_PANEL, WEB veya EXTERNAL.
reasonYalnı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

Webhook istek başlıkları
BaşlıkAnlam
Content-Typeapplication/json
X-Rizaal-Eventconsent.changed, consent.reapproval_required veya ping.
X-Rizaal-DeliveryOlay kimliği (UUID). Yeniden denemede sabit; tekilleştirme anahtarınızdır.
X-Rizaal-TimestampUnix saniye. Her denemede yenilenir.
X-Rizaal-Signaturev1=<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.

Node.js / Express — webhook imza doğrulamajs
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-Delivery değ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 decidedAt alanına göre uygulayın: kayıtlı kararınızdan eski bir decidedAt gelirse yok sayın. occurredAt ve 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.

Yeniden deneme takvimi
Başarısız denemeSonraki 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_required geldiğinde kişiden yeni onay alın ve yeni externalEventId ile 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 ALLOWED durumundaki 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).