Webhooks

Webhooks, sistemlerinizin sıra olayları gerçekleştiğinde — bir sıra numarası katıldığında, çağrıldığında, tamamlandığında ve benzeri durumlarda — gerçek zamanlı HTTP POST bildirimleri almasını sağlar.

Başlarken

admin.jonot.io/settings/integrations adresini açın.
Uç nokta ekle’ye tıklayın.
Sunucunuzun dinlediği herkese açık bir HTTPS URL’si girin.
Hangi olaylara abone olacağınızı seçin.
Kaydet’e tıklayın.

İmzalama gizli anahtarınızı saklayın — yalnızca bir kez gösterilir. Uç noktanızın erişilebilir olduğunu doğrulamak için uç nokta düzenleme sayfasındaki Test isteği gönder düğmesini kullanın.

Olay türleri

Olay adı	Ne zaman tetiklenir
`ticket.joined`	Bir müşteri sıraya katılır
`ticket.called`	Bir personel bir sıra numarasını gişeye çağırır
`ticket.completed`	Bir sıra numarası tamamlandı olarak işaretlenir
`ticket.cancelled`	Bir müşteri veya personel bir sıra numarasını iptal eder
`ticket.skipped`	Bir sıra numarası atlanır (tekrar çağrılabilir bir erteleme)
`ticket.no_show`	Çağrılmış veya atlanmış bir sıra numarası gelmedi olarak onaylanır
`queue.status_changed`	Bir sıranın durumu değişir (`ACTIVE`, `PAUSED` veya `CLOSED`)

Yük (payload) biçimi

Her teslimat, aşağıdakilere sahip bir HTTP POST’tur:

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

Varsayılan gövde bir JSON zarfıdır. payload alanının şekli olaya göre değişir:

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

İmzayı doğrulama

Jonot, her teslimatı aşağıdaki dize üzerinde HMAC-SHA256 ile imzalar:

<deliveryId>.<timestamp>.<body>

Node.js’de (≥18) doğrulamak için:

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);
}

Yük şablonları

Varsayılan JSON gövdesini özel bir şablonla değiştirebilirsiniz. Şablonlar Mustache-lite sözdizimini kullanır:

{{ path.to.value }} — değiştirilir ve içerik türüne göre kaçış uygulanır: application/json için JSON dizesi olarak kaçış uygulanır, application/x-www-form-urlencoded için yüzde kodlanır, text/plain için ham haliyle bırakılır
{{{ path.to.value }}} — ham haliyle değiştirilir (kaçış uygulanmaz)

application/json için örnek şablon (ticket.joined olayına abone):

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

Şablon düzenleyici

Yük şablonu alanı, aşağıdaki özelliklere sahip tam bir kod düzenleyicidir:

JSON şablonları için sözdizimi vurgulama ve parantez eşleştirme.
Değişken paleti — seçtiğiniz olaylar için kullanılabilen her değişken yolu başına bir tane olmak üzere her zaman görünen bir ekleme düğmeleri satırı. İmleç konumuna bir {{ path }} belirteci eklemek için bir düğmeye tıklayın.
Canlı doğrulama — siz yazarken düzenleyici hem JSON yapısını (içerik türü application/json olduğunda ve ham {{{ }}} etiketleri bulunmadığında) hem de değişken yollarını kontrol eder. Tanılar, düzenleyicinin içinde satır içi işaretler olarak ve altında bir özet bandında görünür:
- Hata — seçtiğiniz olayların hiçbirinde bilinmeyen bir yol.
- Uyarı — yalnızca seçtiğiniz olayların bir kısmında bulunan bir yol (diğer olayların teslimatlarında boş olacaktır).

Doğrulama, kaydetme sırasında sunucuda da çalışır — düzenleyicinin geri bildirimi sunucu kurallarını tam olarak yansıtır.

Teslimat yeniden denemeleri

Başarısız teslimatlar (2xx dışı yanıt veya bağlantı hatası), Cloudflare Queues tarafından üstel geri çekilme ile en fazla 3 kez yeniden denenir. 3 başarısızlıktan sonra teslimat ölü mektup kuyruğuna düşer ve uç noktanın ardışık başarısızlık sayacı artar.

Bir uç nokta 20 ardışık başarısızlığa ulaştığında otomatik olarak devre dışı bırakılır. Uç nokta düzenleme sayfasından yeniden etkinleştirin; sayaç sıfıra döner.

Teslimat geçmişi

Her uç noktadaki Teslimatlar sekmesi, son 30 günlük teslimat denemelerini gösterir: olay türü, HTTP durumu, deneme sayısı ve zaman damgası. Daha eski kayıtlara göz atmak için Daha fazla yükle düğmesini kullanın.

Sınırlar

Sınır	Değer
Organizasyon başına uç nokta sayısı	5
Uç nokta başına özel başlık sayısı	10
Başlık değeri uzunluğu	1.024 bayt
Yük şablonu boyutu	16 KB
Teslimat zaman aşımı	10 sn
Teslimat geçmişi saklama süresi	30 gün
Organizasyon başına maksimum teslimat hızı	120 / 60 sn

İmzalama gizli anahtarını döndürme

Uç nokta düzenleme sayfasını açın.
İmzalama gizli anahtarını döndür’e tıklayın.
Döndürmeyi iletişim kutusunda onaylayın.
Yeni gizli anahtarı hemen kopyalayın — yalnızca bir kez gösterilir ve geri alınamaz. İletişim kutusunu kaydetmeden kapatırsanız, yeni bir düz metin elde etmek için tekrar döndürmeniz gerekir.
Sunucunuzu yeni gizli anahtarla imzaları doğrulayacak şekilde güncelleyin.

Örtüşme penceresi yoktur. Eski gizli anahtar, döndürmeyi onayladığınız anda doğrulamayı durdurur. Yeni gizli anahtarı, döndürmeden hemen sonra alıcınıza dağıtmayı planlayın.

Arayüz, hangi gizli anahtarın şu anda geçerli olduğunu doğrulayabilmeniz için Döndür düğmesinin yanında Etkin gizli anahtar: ····XXXX (son dört karakter) gösterir — bir döndürmeden sonra alıcınızın ve sunucunun senkronize olduğunu doğrulamak için kullanışlıdır.

İmzalama gizli anahtarı hijyeni

Ne zaman döndürülmeli:

Sızıntı şüphesi: gizli anahtar bir günlük dosyasında göründü, ayrılan bir çalışanla paylaşıldı veya bir ekran kaydında yakalandı.
Rutin hijyen: periyodik olarak döndürmek, tespit edilmemiş bir sızıntının etki alanını sınırlar.
Gizli anahtarı hangi hizmetlerin okuyabileceğine dair herhangi bir değişiklikten sonra (anahtar yönetimi döndürmesi).

Alıcıyı nasıl güncellersiniz:

Yönetim arayüzünde döndürün ve yeni gizli anahtarı kopyalayın.
Gizli anahtarı alıcınızın gizli anahtar deposunda güncelleyin (ortam değişkeni, gizli anahtar yöneticisi vb.).
Güncellenmiş alıcıyı dağıtın.
Bir sonraki teslimatın Teslimatlar sekmesinde başarılı olduğunu doğrulayın.

Kaydetmeden önce yeni gizli anahtarı kaybettiyseniz:

Tekrar döndürün. Her döndürme yeni bir rastgele gizli anahtar üretir. Önceki düz metin geri alınamaz — sunucu tarafında yalnızca AEAD ile şifrelenmiş bir biçim saklanır.