Webhookok

Fogadja a munkamenetei eseményeit a saját háttérrendszerében: minden kézbesítés HMAC-SHA256 aláírást kap, hiba esetén egyre ritkábban újrapróbálkozunk, és minden kézbesítés egyedi azonosítót visz, hogy a fogadója idempotens lehessen.

Mikor érdemes webhookot használni

Akkor, ha lekérdezgetés nélkül szeretne reagálni arra, ami a teremben történik: a platform hívja Önt, amikor egy munkamenet elindul vagy véget ér, egy kérdés lezárul, vagy véglegesednek az eredményei. A kézbesítés legalább egyszeri – ismétlődhet, de soha nem hiúsul meg némán –, ezért kell a fogadójának idempotensnek lennie.

Eseménykatalógus

Az API szolgálja ki a /public/v1/limits végponton – ez az oldal nem tárol róla másolatot.

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

Fejlécek minden kézbesítésben

  • X-Votinova-EventAz esemény típusa, pontosan úgy, ahogy a katalógusban szerepel.
  • X-Votinova-Delivery-IdKézbesítésenként egyedi – ez a deduplikációs kulcsa.
  • X-Votinova-TimestampEpoch-másodperc; az aláírás része, így egy visszajátszott kézbesítést nem lehet újrakeltezni.
  • X-Votinova-SignatureHMAC-SHA256 hexadecimálisan, előtag nélkül.

A törzs tömör JSON az eseménnyel és minden érintett azonosítóval – bájtra pontosan ez az aláírt mintakézbesítés:

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

Az aláírás ellenőrzése

Minden kézbesítést HMAC-SHA256 aláírással látunk el az időbélyeg, egy pont és a törzs fölött, a végpont titkával kulcsolva. Az eredményt vesse össze az X-Votinova-Signature fejléccel.

  • A NYERS törzset írja alá. Ha feldolgozza és újraszerializálja, megváltoznak a szóközök, és az aláírás már nem fog egyezni.
  • Állandó idejű összehasonlítást használjon, ne == operátort.
Valódi kézbesítéssel ellenőrizve
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

Újrapróbálkozások

Webhook-kézbesítés: legfeljebb 8 próbálkozás, egyre hosszabb, 21, 45, 95, 171, 369, 732, 1480 másodperces várakozással. Ha ezek elfogytak, a kézbesítés véglegesen sikertelen lesz, és kézzel újraküldhető.

Idempotencia

Az X-Votinova-Delivery-Id fejlécet használja deduplikációs kulcsként: egy kézbesítés többször is megérkezhet, a hatása viszont csak egyszer léphet életbe.

X-Votinova-Delivery-Id

Bevált gyakorlatok

  • Válaszoljon 200-zal, amint a kézbesítés biztonságban van, és a feldolgozást bízza a saját sorára – a lassú fogadó feltornyozza az újrapróbálkozásokat.
  • MINDIG ellenőrizze az aláírást a feldolgozás előtt: enélkül bárki eseményeket találhat ki, aki ismeri az URL-jét.
  • Deduplikáljon az X-Votinova-Delivery-Id alapján: a legalább egyszeri kézbesítés azt jelenti, hogy ugyanaz kétszer is befuthat.
  • 10 egymást követő sikertelen kézbesítés után a végpont magát szünetelteti; ha a fogadója újra üzemel, kapcsolja vissza a panelről vagy API-ból.