Webhookit

Webhookit lähettävät järjestelmillesi reaaliaikaisia HTTP POST -ilmoituksia jonotapahtumista, kuten vuoronumeron liittymisestä, kutsumisesta ja valmistumisesta.

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 allekirjoitussalaisuus, sillä se näytetään vain kerran. Tarkista päätepisteen tavoitettavuus muokkaussivun Lähetä testipyyntö -painikkeella.

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 omalla 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

Cloudflare Queues yrittää epäonnistunutta toimitusta uudelleen enintään 3 kertaa ja pidentää viivettä jokaisen yrityksen välillä. Toimitus epäonnistuu, jos päätepiste palauttaa muun kuin 2xx-vastauksen tai yhteydessä tapahtuu virhe. Jos ensimmäinen yritys ja kaikki 3 uudelleenyritystä epäonnistuvat, toimitus siirtyy 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.

Vanha ja uusi salaisuus eivät toimi samanaikaisesti. Vanha salaisuus lakkaa toimimasta heti, kun vahvistat vaihdon. Päivitä webhookit vastaanottava järjestelmä heti vaihdon jälkeen.

Käyttöliittymä näyttää Vaihda-painikkeen vieressä tekstin Aktiivinen salaisuus: ····XXXX. Neljän viimeisen merkin avulla voit tarkistaa, mikä salaisuus on käytössä 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.
Säännöllinen vaihto: vaihtaminen rajoittaa aikaa, jonka vuotanutta salaisuutta voi käyttää.
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.