Webhook notikumi

Saņemiet savu sesiju notikumus savā serverī: katra piegāde ir parakstīta ar HMAC-SHA256, tiek atkārtota pieaugošos intervālos un satur unikālu identifikatoru, lai jūsu uztvērējs varētu būt idempotents.

Kad izmantot webhook notikumus

Lai reaģētu uz notiekošo istabā bez pastāvīgas aptaujāšanas: platforma jums piezvana, kad sesija sākas vai beidzas, kad jautājums tiek slēgts vai kad tā rezultāti tiek fiksēti. Piegāde ir vismaz vienu reizi – tā var atkārtoties, bet nekad klusi nepazūd – tāpēc jūsu uztvērējam jābūt idempotentam.

Notikumu katalogs

To sniedz API adresē /public/v1/limits – šī lapa nekādu kopiju neglabā.

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

Galvenes katrā piegādē

  • X-Votinova-EventNotikuma veids, tieši tāds, kāds tas ir katalogā.
  • X-Votinova-Delivery-IdUnikāls katrai piegādei – jūsu dublikātu novēršanas atslēga.
  • X-Votinova-TimestampSekundes no epohas sākuma; tās ietilpst parakstā, tāpēc atkārtotas piegādes datumu nevar mainīt.
  • X-Votinova-SignatureHMAC-SHA256 heksadecimālā formātā, bez prefiksa.

Saturs ir kompakts JSON ar notikumu un visiem saistītajiem identifikatoriem – šis ir baits pa baitam parakstītas piegādes piemērs:

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

Paraksta pārbaude

Katra piegāde tiek parakstīta ar HMAC-SHA256 no laikspiedola, punkta un satura, izmantojot galapunkta noslēpumu kā atslēgu. Rezultātu salīdziniet ar X-Votinova-Signature galveni.

  • Parakstiet NEAPSTRĀDĀTO saturu. To nolasot un pārrakstot, mainās atstarpes, un paraksts vairs nesakrīt.
  • Salīdziniet nemainīgā laikā, nevis ar ==.
Pārbaudīts ar reālu piegādi
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

Atkārtojumi

Webhook piegādes: līdz 8 mēģinājumiem, ar arvien garākām pauzēm – 21, 45, 95, 171, 369, 732, 1480 sekundes. Kad mēģinājumi izsmelti, piegāde nonāk neizdevušos rindā, un to var atkārtot manuāli.

Idempotence

Izmantojiet X-Votinova-Delivery-Id kā dublikātu novēršanas atslēgu: piegāde var pienākt vairāk nekā vienu reizi, bet jūsu darbībai jānotiek tikai vienu reizi.

X-Votinova-Delivery-Id

Laba prakse

  • Atbildiet ar 200, tiklīdz piegāde ir droši saņemta, un apstrādājiet to savā rindā – lēns uztvērējs uzkrāj atkārtojumus.
  • VIENMĒR pārbaudiet parakstu pirms satura nolasīšanas: bez tā jebkurš, kas zina jūsu adresi, var izdomāt notikumus.
  • Novērsiet dublikātus pēc X-Votinova-Delivery-Id: „vismaz vienu reizi“ nozīmē, ka viena piegāde var pienākt divreiz.
  • Pēc 10 neveiksmēm pēc kārtas galapunkts pats tiek pauzēts; kad jūsu uztvērējs atkal darbojas, ieslēdziet to no paneļa vai caur API.