Webhook įvykiai

Gaukite savo sesijų įvykius savo serverio pusėje: kiekvienas pristatymas pasirašytas HMAC-SHA256, kartojamas didėjančiais intervalais ir turi unikalų identifikatorių, kad jūsų imtuvas galėtų būti idempotentinis.

Kada verta naudoti webhook įvykius

Kad reaguotumėte į tai, kas vyksta kambaryje, be nuolatinės apklausos: platforma jums paskambina, kai sesija prasideda ar baigiasi, kai klausimas užsidaro arba kai jo rezultatai užfiksuojami. Pristatymas yra bent vieną kartą – jis gali pasikartoti, bet niekada tyliai nedingsta – todėl jūsų imtuvas turi būti idempotentinis.

Įvykių katalogas

Pateikiamas API adresu /public/v1/limits – šis puslapis jokios kopijos nesaugo.

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

Antraštės kiekviename pristatyme

  • X-Votinova-EventĮvykio tipas, lygiai toks, koks yra kataloge.
  • X-Votinova-Delivery-IdUnikalus kiekvienam pristatymui – jūsų dubliavimo šalinimo raktas.
  • X-Votinova-TimestampSekundės nuo epochos pradžios; jos įeina į parašą, tad pakartotinio pristatymo data pakeisti negalima.
  • X-Votinova-SignatureHMAC-SHA256 šešioliktainiu formatu, be priešdėlio.

Turinys yra kompaktiškas JSON su įvykiu ir visais susijusiais identifikatoriais – tai baitas į baitą pasirašyto pristatymo pavyzdys:

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

Parašo tikrinimas

Kiekvienas pristatymas pasirašomas HMAC-SHA256 algoritmu iš laiko žymos, taško ir turinio, naudojant galinio taško paslaptį kaip raktą. Rezultatą palyginkite su X-Votinova-Signature antrašte.

  • Pasirašykite NEAPDOROTĄ turinį. Jį perskaičius ir vėl užrašius pasikeičia tarpai, o parašas nebesutampa.
  • Lyginkite pastoviu laiku, o ne su ==.
Patikrinta su tikru pristatymu
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

Kartojimai

Webhook pristatymai: iki 8 bandymų, laukiant vis ilgiau – 21, 45, 95, 171, 369, 732, 1480 sekundžių. Kai bandymai išnaudojami, pristatymas patenka į nepavykusiųjų eilę ir jį galima pakartoti rankiniu būdu.

Idempotentiškumas

Naudokite X-Votinova-Delivery-Id kaip dubliavimo šalinimo raktą: pristatymas gali ateiti daugiau nei kartą, o jūsų veiksmas turi įvykti tik vieną kartą.

X-Votinova-Delivery-Id

Geroji praktika

  • Atsakykite 200, vos tik pristatymas saugiai priimtas, o apdorokite savo eilėje – lėtas imtuvas kaupia kartojimus.
  • VISADA patikrinkite parašą prieš skaitydami turinį: be to bet kas, žinantis jūsų adresą, gali išgalvoti įvykius.
  • Šalinkite dublikatus pagal X-Votinova-Delivery-Id: „bent vieną kartą“ reiškia, kad tas pats pristatymas gali ateiti du kartus.
  • Po 10 nesėkmių iš eilės galinis taškas pats pristabdomas; kai jūsų imtuvas vėl veikia, įjunkite jį iš skydelio arba per API.