Webhook’lar

Oturumlarınızın olaylarını arka ucunuzda alın: her teslimat HMAC-SHA256 ile imzalanır, üstel artan bekleyişle yeniden denenir ve benzersiz bir kimlik taşır; böylece alıcınız idempotent olabilir.

Webhook’ları ne zaman kullanmalı

Odada olup biteni sürekli sorgulamadan izlemek için: bir oturum başladığında ya da bittiğinde, bir soru kapandığında ya da sonuçları kesinleştiğinde platform sizi çağırır. Teslimat en az bir kezdir — tekrarlayabilir, ama sessizce başarısız olmaz — bu yüzden alıcınız idempotent olmalıdır.

Olay kataloğu

API tarafından /public/v1/limits adresinden sunulur — bu sayfa hiçbir kopya tutmaz.

  • presentation.import.completed
  • presentation.import.failed
  • question.activated
  • question.closed
  • question.results.finalized
  • report.ready
  • session.ended
  • session.paused
  • session.resumed
  • session.started

Her teslimattaki başlıklar

  • X-Votinova-EventOlay türü, katalogda göründüğü şekliyle.
  • X-Votinova-Delivery-IdHer teslimat için benzersiz — yineleme ayıklama anahtarınız.
  • X-Votinova-TimestampEpoch saniyesi; imzalananın bir parçasıdır, böylece yeniden oynatılan bir teslimatın tarihi değiştirilemez.
  • X-Votinova-SignatureOnaltılık HMAC-SHA256, ön ek olmadan.

Gövde, olayı ve ilgili tüm kimlikleri taşıyan derli toplu bir JSON’dur — aşağıdaki, byte byte, imzalanmış örnek teslimattır:

{"event":"session.ended","session_id":"68b2e3d4c5f607182930a5bc"}

İmzayı doğrulama

Her teslimat; zaman damgası, bir nokta ve gövde üzerinden, uç noktanın gizli anahtarıyla HMAC-SHA256 ile imzalanır. Sonucu X-Votinova-Signature başlığıyla karşılaştırın.

  • HAM gövdeyi imzalayın. Ayrıştırıp yeniden dizileştirmek boşlukları değiştirir ve imza tutmaz olur.
  • Sabit zamanda karşılaştırın, == ile değil.
Gerçek bir teslimatla doğrulandı
const crypto = require("node:crypto");

function verify(headers, rawBody, secret) {
  const timestamp = headers["x-votinova-timestamp"];
  const signature = headers["x-votinova-signature"];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
secret     whsec_3f8a1c92d4e5b6a7
timestamp  1785321600
body       {"event":"session.ended","session_id":"68b2e3d4c5f607182930a5bc"}

HMAC-SHA256(secret, timestamp + "." + body)
= 10a86171bd92f5fcf8c28b873978e0214302cc2291c54cc016d18347f3ee7c38

Yeniden denemeler

Webhook teslimatları: en fazla 8 deneme; bekleyişler 21, 45, 95, 171, 369, 732, 1480 saniye olarak artar. Tümü tükendiğinde teslimat teslim edilemeyenlere taşınır ve elle yeniden gönderilebilir.

İdempotentlik

Yinelenenleri ayıklama anahtarı olarak X-Votinova-Delivery-Id kullanın: bir teslimat birden çok kez gelebilir ve etkisi yalnızca bir kez uygulanmalıdır.

X-Votinova-Delivery-Id

En iyi uygulamalar

  • Teslimat güvendeyse hemen 200 yanıtı verin ve işlemeyi kendi kuyruğunuzda yapın — yavaş bir alıcı yeniden denemeleri biriktirir.
  • Ayrıştırmadan önce imzayı HER ZAMAN doğrulayın: imza olmadan adresinizi bilen herkes olay uydurabilir.
  • X-Votinova-Delivery-Id ile yinelenenleri ayıklayın: en az bir kez, aynı teslimatın iki kez gelebileceği anlamına gelir.
  • Art arda 10 başarısızlıktan sonra uç nokta kendini duraklatır; alıcınız geri döndüğünde panelden ya da API üzerinden yeniden etkinleştirin.