Webhooks

Webhooks hutuma ombi la HTTP POST kwenye mfumo wako wakati tukio la foleni linapotokea. Matukio ni pamoja na tiketi kujiunga na foleni, kuitwa, au kukamilika.

Kuanza

Fungua admin.jonot.io/settings/integrations.
Bofya Ongeza sehemu ya mwisho.
Ingiza URL ya umma ya HTTPS inayopokea maombi kwenye seva yako.
Chagua matukio unayotaka kujiandikisha kupokea.
Bofya Hifadhi.

Nakili na uhifadhi siri yako ya uthibitishaji inapoonekana. Jonot huionyesha mara moja tu. Ili kuhakikisha kuwa Jonot inaweza kufikia sehemu yako ya mwisho, tumia kitufe cha Tuma ombi la majaribio katika ukurasa wa kuhariri sehemu ya mwisho.

Aina za matukio

Jina la tukio	Jonot inapolituma
`ticket.joined`	Mteja anajiunga na foleni
`ticket.called`	Mfanyakazi anaita tiketi kwenye dawati la huduma
`ticket.completed`	Tiketi inawekwa alama ya kukamilika
`ticket.cancelled`	Mteja au mfanyakazi anaghairi tiketi
`ticket.skipped`	Tiketi inarukwa (uahirishaji unaoweza kuitwa tena)
`ticket.no_show`	Tiketi iliyoitwa au kurukwa inathibitishwa kutokuwepo
`queue.status_changed`	Hali ya foleni inabadilika (`ACTIVE`, `PAUSED`, au `CLOSED`)

Muundo wa mzigo

Kila uwasilishaji ni HTTP POST yenye:

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

Mwili wa kawaida ni kitu cha JSON. Yaliyomo katika sehemu ya payload yanategemea tukio:

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"
  }
}

Kuhakiki saini

Jonot inasaini kila uwasilishaji kwa HMAC-SHA256 juu ya mfuatano huu:

<deliveryId>.<timestamp>.<body>

Kuhakiki katika Node.js (≥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);
}

Violezo vya mzigo

Unaweza kubadilisha mwili wa kawaida wa JSON na kiolezo maalum. Violezo hutumia sintaksia hii ya Mustache-lite:

{{ path.to.value }} — Jonot huweka thamani na kuichakata kulingana na aina ya maudhui. Hutumia uchakataji wa mfuatano wa JSON kwa application/json, usimbaji wa asilimia kwa application/x-www-form-urlencoded, na hakuna uchakataji kwa text/plain.
{{{ path.to.value }}} — Jonot huweka thamani bila kuichakata.

Mfano wa kiolezo kwa application/json (kilichojiandikisha kwa ticket.joined):

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

Kihariri cha kiolezo

Sehemu ya kiolezo cha mzigo ni kihariri kamili cha msimbo chenye:

Uangaziaji wa sintaksia na ulinganishaji wa mabano kwa violezo vya JSON.
Orodha ya vigezo — safu ya vitufe vya njia za vigezo zinazopatikana kwa matukio uliyochagua. Bofya kitufe ili kuweka alama ya {{ path }} mahali pa kishale.
Uthibitishaji wa moja kwa moja — unapoandika, kihariri kinaangalia njia za vigezo. Pia kinaangalia muundo wa JSON wakati aina ya maudhui ni application/json na kiolezo hakina lebo ghafi za {{{ }}}. Kihariri kinaweka alama kwenye matatizo ndani ya msimbo na kuyaorodhesha chini yake:
- Hitilafu — njia isiyojulikana katika matukio yote uliyochagua.
- Onyo — njia inayopatikana kwa baadhi tu ya matukio uliyochagua (itakuwa tupu kwa uwasilishaji wa matukio mengine).

Seva hutumia kanuni zilezile za uthibitishaji unapohifadhi.

Kujaribu tena uwasilishaji

Cloudflare Queues hujaribu tena uwasilishaji ulioshindwa hadi mara 3, ikiongeza muda wa kusubiri kabla ya kila jaribio. Uwasilishaji unashindwa wakati sehemu ya mwisho inarudisha hali nje ya safu ya 2xx au wakati kuna hitilafu ya muunganisho. Ikiwa jaribio la kwanza na majaribio yote 3 ya kurudia yatashindwa, uwasilishaji unahamia kwenye foleni ya ujumbe ulioshindikana (dead-letter queue), na hesabu ya kushindwa mfululizo ya sehemu ya mwisho inaongezeka.

Jonot huzima sehemu ya mwisho kiotomatiki baada ya kushindwa mara 20 mfululizo. Unaweza kuiwasha tena kutoka ukurasa wa kuhariri sehemu ya mwisho. Hii inarudisha hesabu hiyo sifuri.

Historia ya uwasilishaji

Kichupo cha Uwasilishaji cha kila sehemu ya mwisho kinaonyesha majaribio ya uwasilishaji ya siku 30 zilizopita. Kila rekodi ina aina ya tukio, hali ya HTTP, idadi ya majaribio, na muhuri wa muda. Tumia kitufe cha Pakia zaidi kuona rekodi za zamani zaidi ndani ya kipindi hicho.

Vikomo

Kikomo	Thamani
Sehemu za mwisho kwa kila shirika	5
Vichwa maalum kwa sehemu ya mwisho	10
Urefu wa thamani ya kichwa	baiti 1 024
Ukubwa wa kiolezo cha mzigo	16 KB
Muda wa kusubiri uwasilishaji	sekunde 10
Uhifadhi wa historia ya uwasilishaji	siku 30
Kiwango cha juu cha uwasilishaji kwa shirika	120 / sekunde 60

Kuzungusha siri ya uthibitishaji

Fungua ukurasa wa kuhariri sehemu ya mwisho.
Bofya Zungushia siri ya uthibitishaji.
Thibitisha uzunguzishaji katika kisanduku cha mazungumzo.
Nakili siri mpya mara moja. Jonot huionyesha mara moja tu na haiwezi kuirejesha. Ukifunga kisanduku cha mazungumzo bila kuihifadhi, zungusha siri tena ili kupata thamani mpya.
Sasisha seva yako ili kuhakiki saini kwa siri mpya.

Siri ya zamani na siri mpya hazifanyi kazi kwa wakati mmoja. Siri ya zamani inaacha kuhakiki maombi mara tu unapothibitisha uzunguzishaji. Sasisha mfumo unaopokea webhooks zako mara moja baada ya kuzungusha.

Kiolesura kinaonyesha Active secret: ····XXXX karibu na kitufe cha Kuzungusha. Herufi nne za mwisho zinakusaidia kuthibitisha ni siri gani inayotumika baada ya uzunguzishaji.

Usafi wa siri ya uthibitishaji

Wakati wa kuzungusha:

Tuhuma ya kuvuja: siri ilionekana katika faili la kumbukumbu, ilishirikiwa na mfanyakazi anayeondoka, au ilinaswa katika rekodi ya skrini.
Uzunguzishaji wa kawaida: kubadilisha siri mara kwa mara kunapunguza muda ambao siri iliyovuja inaweza kutumika.
Mabadiliko ya ufikiaji: zungusha siri baada ya kubadilisha ni huduma zipi zinazoweza kuisoma.

Jinsi ya kusasisha mpokezi:

Zungusha katika kiolesura cha usimamizi na unakili siri mpya.
Sasisha siri inayotumiwa na mfumo unaopokea. Ihifadhi katika kigezo cha mazingira, msimamizi wa siri, au hifadhi nyingine salama ya siri.
Peleka mfumo uliosasishwa unaopokea.
Thibitisha kuwa uwasilishaji unaofuata umefaulu katika kichupo cha Uwasilishaji.

Ukipoteza siri mpya kabla ya kuihifadhi:

Zungusha tena. Kila uzunguzishaji unazalisha siri mpya ya nasibu. Jonot haiwezi kurejesha thamani ya awali inayosomeka kwa sababu seva huhifadhi umbo lililosimbwa fiche tu.