Webhookid

Võtke oma sessioonide sündmused vastu oma taustasüsteemis: iga edastus on allkirjastatud HMAC-SHA256-ga, seda korratakse kasvava ootega ja see kannab unikaalset id-d, et teie vastuvõtja saaks olla idempotentne.

Millal webhooke kasutada

Selleks, et reageerida ruumis toimuvale ilma pidevalt pärimata: platvorm helistab teile, kui sessioon algab või lõpeb, kui küsimus suletakse või kui selle tulemused muutuvad lõplikuks. Edastus toimub vähemalt üks kord – see võib korduda, kuid ei kao kunagi vaikselt ära – ja just seepärast peab teie vastuvõtja olema idempotentne.

Sündmuste kataloog

Selle pakub API aadressil /public/v1/limits – see leht ei hoia oma koopiat.

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

Päised igal edastusel

  • X-Votinova-EventSündmuse tüüp täpselt sellisena, nagu see kataloogis on.
  • X-Votinova-Delivery-IdUnikaalne iga edastuse kohta – teie dubleerimise võti.
  • X-Votinova-TimestampSekundid alates epohhi algusest; osa allkirjastatavast, nii et korduvat edastust ei saa uue kuupäevaga varustada.
  • X-Votinova-SignatureHMAC-SHA256 kuueteistkümnendkujul, ilma eesliiteta.

Keha on kompaktne JSON, milles on sündmus ja kõik seotud id-d – see on bait-baidilt allkirjastatud näidisedastus:

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

Allkirja kontrollimine

Iga edastus allkirjastatakse HMAC-SHA256-ga ajatempli, punkti ja keha põhjal, kasutades võtmena lõpp-punkti saladust. Võrrelge tulemust päisega X-Votinova-Signature.

  • Allkirjastage TOORES keha. Parsimine ja uuesti serialiseerimine muudab tühikuid ja allkiri ei klapi enam.
  • Võrrelge püsiva ajaga, mitte operaatoriga ==.
Kontrollitud päris edastuse peal
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

Korduskatsed

Webhooki edastused: katseid kuni 8, kasvava ootega 20, 42, 81, 160, 335, 762, 1468 sekundit. Kui katsed on ammendatud, läheb edastus loobutute hulka ja selle saab käsitsi uuesti saata.

Idempotentsus

Kasutage X-Votinova-Delivery-Id väärtust dubleerimise võtmena: edastus võib saabuda rohkem kui üks kord ja teie toiming tohib rakenduda ainult ühe korra.

X-Votinova-Delivery-Id

Parimad tavad

  • Vastake 200-ga kohe, kui edastus on turvaliselt hoiule pandud, ja töödelge see oma järjekorras – aeglane vastuvõtja kuhjab korduskatseid.
  • Kontrollige ALATI allkirja enne parsimist: ilma selleta saab igaüks, kes teie aadressi teab, sündmusi välja mõelda.
  • Eemaldage duplikaadid X-Votinova-Delivery-Id järgi: vähemalt üks kord tähendab, et sama edastus võib jõuda kaks korda.
  • Pärast 10 järjestikust ebaõnnestumist paneb lõpp-punkt end ise pausile; lülitage see paneelilt või API kaudu uuesti sisse, kui teie vastuvõtja on taas töös.