Webhookit

Webhookien avulla järjestelmäsi voivat vastaanottaa reaaliaikaisia HTTP POST -ilmoituksia jonotapahtumista — vuoronumero liittyy, kutsutaan, valmistuu ja niin edelleen.

Aloittaminen

Avaa admin.jonot.io/settings/integrations.
Napsauta Lisää päätepiste.
Syötä julkinen HTTPS-URL, jota palvelimesi kuuntelee.
Valitse tapahtumat, joita haluat tilata.
Napsauta Tallenna päätepiste.

Tallenna allekirjoitussalaisuutesi — se näytetään vain kerran. Varmistaaksesi, että päätepisteesi on tavoitettavissa, käytä päätepisteen muokkaussivun Lähetä testipyyntö -painiketta.

Tapahtumatyypit

Tapahtuman nimi	Milloin se laukeaa
`ticket.joined`	Asiakas liittyy jonoon
`ticket.called`	Henkilöstön jäsen kutsuu vuoronumeron palvelupisteelle
`ticket.completed`	Vuoronumero merkitään valmiiksi
`ticket.cancelled`	Asiakas tai henkilöstön jäsen peruuttaa vuoronumeron
`ticket.skipped`	Vuoronumero ohitetaan (takaisinkutsuttavissa oleva lykkäys)
`ticket.no_show`	Kutsuttu tai ohitettu vuoronumero vahvistetaan poissaolevaksi
`queue.status_changed`	Jonon tila muuttuu (`ACTIVE`, `PAUSED` tai `CLOSED`)

Hyötykuorman muoto

Jokainen toimitus on HTTP POST, jossa on:

Content-Type: application/json
X-Jonot-Event: ticket.called
X-Jonot-Delivery-Id: <uuid>
X-Jonot-Timestamp: 2024-06-01T12:00:00.000Z
X-Jonot-Signature: v1,<base64-hmac-sha256>
X-Jonot-Payload-Version: v1

Oletusrunko on JSON-kirjekuori. payload-kentän muoto vaihtelee tapahtuman mukaan:

ticket.joined

{
  "deliveryId": "<uuid>",
  "event": "ticket.joined",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "org": { "id": "org_…", "name": "My Org" },
  "payload": {
    "ticket": { "id": "tkt_…", "queueId": "q_…" },
    "queue": { "id": "q_…", "name": "Main Queue" },
    "location": { "id": "loc_…", "name": "Downtown" }
  }
}

ticket.called / ticket.completed / ticket.skipped / ticket.no_show

{
  "deliveryId": "<uuid>",
  "event": "ticket.called",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "org": { "id": "org_…", "name": "My Org" },
  "payload": {
    "ticket": {
      "id": "tkt_…",
      "number": 42,
      "status": "CALLED",
      "queueId": "q_…",
      "createdAt": "2024-06-01T11:58:00.000Z",
      "updatedAt": "2024-06-01T12:00:00.000Z"
    }
  }
}

ticket.cancelled

{
  "deliveryId": "<uuid>",
  "event": "ticket.cancelled",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "org": { "id": "org_…", "name": "My Org" },
  "payload": {
    "ticketId": "tkt_…",
    "queueId": "q_…"
  }
}

queue.status_changed

{
  "deliveryId": "<uuid>",
  "event": "queue.status_changed",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "org": { "id": "org_…", "name": "My Org" },
  "payload": {
    "queueId": "q_…",
    "status": "PAUSED"
  }
}

Allekirjoituksen varmentaminen

Jonot allekirjoittaa jokaisen toimituksen HMAC-SHA256:lla seuraavasta merkkijonosta:

<deliveryId>.<timestamp>.<body>

Varmentaminen Node.js:ssä (≥18):

import { createHmac, timingSafeEqual } from "node:crypto";

/**
 * Returns true when the signature header is valid and the timestamp is
 * within 5 minutes of now. Throws for malformed input.
 */
function verifySignature(secret, deliveryId, timestamp, body, header) {
  // Replay-attack guard: reject deliveries older than 5 minutes.
  const ageMs = Date.now() - new Date(timestamp).getTime();
  if (Math.abs(ageMs) > 5 * 60 * 1000) return false;

  const expected =
    "v1," +
    createHmac("sha256", secret)
      .update(`${deliveryId}.${timestamp}.${body}`)
      .digest("base64");

  // timingSafeEqual prevents timing-oracle attacks.
  // Buffers must be the same length — if lengths differ the signature is
  // invalid, but we still compare a dummy value to keep constant time.
  const expectedBuf = Buffer.from(expected);
  const headerBuf = Buffer.from(header);
  if (expectedBuf.length !== headerBuf.length) return false;
  return timingSafeEqual(expectedBuf, headerBuf);
}

Hyötykuorman mallit

Voit korvata oletusarvoisen JSON-rungon mukautetulla mallilla. Mallit käyttävät kevennettyä Mustache-syntaksia:

{{ path.to.value }} — korvataan ja suojataan sisältötyypin mukaan: JSON-merkkijonoksi suojattuna tyypille application/json, prosenttikoodattuna tyypille application/x-www-form-urlencoded, sellaisenaan tyypille text/plain
{{{ path.to.value }}} — korvataan sellaisenaan (ei suojausta)

Esimerkkimalli tyypille application/json (tilattuna tapahtumaan ticket.joined):

{
  "type": "{{ event }}",
  "ticketId": "{{ payload.ticket.id }}",
  "queueName": "{{ payload.queue.name }}"
}

Mallieditori

Hyötykuorman mallikenttä on täysi koodieditori, jossa on:

Syntaksin korostus ja sulkeiden täsmäytys JSON-malleille.
Muuttujapaletti — aina näkyvä rivi lisäyspainikkeita, yksi kutakin valitsemiesi tapahtumien käytettävissä olevaa muuttujapolkua kohden. Napsauta painiketta lisätäksesi {{ path }}-tunnisteen kohdistimen kohdalle.
Reaaliaikainen validointi — kirjoittaessasi editori tarkistaa sekä JSON-rakenteen (kun sisältötyyppi on application/json eikä raakoja {{{ }}}-tunnisteita ole käytössä) että muuttujapolut. Diagnostiikka näkyy editorissa rivikohtaisina merkintöinä ja sen alla yhteenvetobannerina:
- Virhe — polku, joka on tuntematon kaikissa valitsemissasi tapahtumissa.
- Varoitus — polku, joka on olemassa vain osassa valitsemistasi tapahtumista (se on tyhjä muiden tapahtumien toimituksissa).

Validointi suoritetaan myös tallennuksen yhteydessä palvelimella — editorin palaute vastaa täsmälleen palvelimen sääntöjä.

Toimitusten uudelleenyritykset

Epäonnistuneita toimituksia (muu kuin 2xx-vastaus tai yhteysvirhe) yritetään Cloudflare Queuesin toimesta uudelleen enintään 3 kertaa eksponentiaalisella viiveellä. 3 epäonnistumisen jälkeen toimitus päätyy kuolleiden kirjeiden jonoon, ja päätepisteen peräkkäisten epäonnistumisten laskuri kasvaa.

Kun päätepisteelle kertyy 20 peräkkäistä epäonnistumista, se poistetaan automaattisesti käytöstä. Ota se uudelleen käyttöön päätepisteen muokkaussivulta; laskuri nollautuu.

Toimitushistoria

Jokaisen päätepisteen Toimitukset-välilehti näyttää viimeisten 30 päivän toimitusyritykset: tapahtumatyyppi, HTTP-tila, yritysmäärä ja ajankohta. Käytä Lataa lisää -painiketta selataksesi vanhempia tietueita.

Rajat

Raja	Arvo
Päätepisteitä per organisaatio	5
Mukautettuja otsakkeita per päätepiste	10
Otsakearvon pituus	1 024 tavua
Hyötykuorman mallin koko	16 kt
Toimituksen aikakatkaisu	10 s
Toimitushistorian säilytysaika	30 päivää
Suurin toimitusnopeus per organisaatio	120 / 60 s

Allekirjoitussalaisuuden vaihtaminen

Avaa päätepisteen muokkaussivu.
Napsauta Vaihda allekirjoitussalaisuus.
Vahvista vaihto valintaikkunassa.
Kopioi uusi salaisuus välittömästi — se näytetään vain kerran, eikä sitä voi palauttaa. Jos suljet valintaikkunan tallentamatta sitä, sinun on vaihdettava se uudelleen saadaksesi uuden selkokielisen arvon.
Päivitä palvelimesi varmentamaan allekirjoitukset uudella salaisuudella.

Päällekkäisyysikkunaa ei ole. Vanha salaisuus lakkaa toimimasta heti, kun vahvistat vaihdon. Suunnittele uuden salaisuuden käyttöönotto vastaanottajallesi välittömästi vaihdon jälkeen.

Käyttöliittymä näyttää tekstin Aktiivinen salaisuus: ····XXXX (neljä viimeistä merkkiä) Vaihda-painikkeen vieressä, jotta voit tarkistaa, mikä salaisuus on juuri nyt voimassa — hyödyllistä varmistaaksesi, että vastaanottajasi ja palvelin ovat synkronoituja vaihdon jälkeen.

Allekirjoitussalaisuuden hygienia

Milloin vaihtaa:

Epäilty vaarantuminen: salaisuus ilmestyi lokitiedostoon, jaettiin lähtevälle työntekijälle tai tallentui näytön tallenteeseen.
Rutiinihygienia: säännöllinen vaihtaminen rajoittaa havaitsemattoman vuodon vaikutusalaa.
Aina kun muuttuu, mitkä palvelut voivat lukea salaisuuden (avaintenhallinnan vaihto).

Vastaanottajan päivittäminen:

Vaihda salaisuus admin-käyttöliittymässä ja kopioi uusi salaisuus.
Päivitä salaisuus vastaanottajasi salaisuusvarastoon (ympäristömuuttuja, salaisuuksien hallintajärjestelmä jne.).
Julkaise päivitetty vastaanottaja.
Vahvista seuraavan toimituksen onnistuminen Toimitukset-välilehdellä.

Jos kadotit uuden salaisuuden ennen sen tallentamista:

Vaihda salaisuus uudelleen. Jokainen vaihto luo uuden satunnaisen salaisuuden. Edellistä selkokielistä arvoa ei voi palauttaa — palvelimelle tallennetaan vain AEAD-salattu muoto.