Webhookovi

Primajte događaje svojih sesija u vlastitom sustavu: svaka je isporuka potpisana HMAC-SHA256, ponavlja se uz eksponencijalnu odgodu i nosi jedinstveni id da Vaš primatelj može biti idempotentan.

Kada koristiti webhookove

Da reagirate na ono što se događa u sobi bez stalnog ispitivanja: platforma Vas zove kad sesija počne ili završi, kad se pitanje zatvori ili kad se njegovi rezultati objave. Isporuka je barem jednom – može se ponoviti, ali nikad ne zataji u tišini – i zato Vaš primatelj mora biti idempotentan.

Katalog događaja

Poslužuje ga API na /public/v1/limits – ova stranica ne čuva kopiju.

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

Zaglavlja u svakoj isporuci

  • X-Votinova-EventVrsta događaja, točno kako stoji u katalogu.
  • X-Votinova-Delivery-IdJedinstveno po isporuci – Vaš ključ za uklanjanje duplikata.
  • X-Votinova-TimestampSekunde od epohe; dio je onoga što se potpisuje, pa ponovljena isporuka ne može dobiti novi datum.
  • X-Votinova-SignatureHMAC-SHA256 heksadekadski, bez prefiksa.

Tijelo je sažeti JSON s događajem i svim uključenim identifikatorima – ovo je, bajt po bajt, potpisana primjer-isporuka:

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

Provjera potpisa

Svaka je isporuka potpisana algoritmom HMAC-SHA256 nad vremenskom oznakom, točkom i tijelom, ključem tajne te krajnje točke. Usporedite rezultat sa zaglavljem X-Votinova-Signature.

  • Potpisujte SIROVO tijelo. Obrada i ponovno serijaliziranje mijenjaju razmake i potpis se prestaje podudarati.
  • Uspoređujte u stalnom vremenu, ne operatorom ==.
Provjereno na stvarnoj isporuci
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

Ponovni pokušaji

Isporuke webhooka: najviše 8 pokušaja, uz sve dulje čekanje od 21, 45, 95, 171, 369, 732, 1480 sekundi. Kad se iscrpe, isporuka postaje trajno neisporučena i može se ručno ponovno poslati.

Idempotentnost

Koristite X-Votinova-Delivery-Id kao ključ za uklanjanje duplikata: isporuka može stići više puta, a Vaš se učinak smije primijeniti samo jednom.

X-Votinova-Delivery-Id

Dobre prakse

  • Odgovorite sa 200 čim je isporuka na sigurnom i obradite je u vlastitom redu – spor primatelj gomila ponovne pokušaje.
  • UVIJEK provjerite potpis prije obrade: bez toga svatko tko zna Vaš URL može izmišljati događaje.
  • Uklanjajte duplikate po X-Votinova-Delivery-Id: barem jednom znači da ista isporuka može doći dvaput.
  • Nakon 10 uzastopnih neuspjeha krajnja se točka sama pauzira; ponovno je omogućite iz ploče ili preko API-ja kad Vam se primatelj vrati.