Webhook'lar

Bir şey olduğunda HTTPS POST alın: herhangi bir yerde fiş işlendiğinde, ödül açıldığında, masadan sipariş verildiğinde.

Olaylar, bu işletmede API üzerinden yapılan her şeyi kapsar: sizin entegrasyonunuzun ve diğer entegrasyonların (başka bir kasa, kiosk, randevu entegrasyonu) yaptıklarını. Yalnızca kullandığınız olaylara abone olun.

Uç nokta ekleyin

Geliştiriciler → Webhooks bölümünden veya API ile. URL herkese açık bir HTTPS adresi olmalıdır. İmza anahtarı yalnızca bir kez, uç nokta oluşturulurken döner.

curl

curl https://loyaltyfy.io/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://pos.example.com/loyaltyfy/webhooks",
    "events": ["transaction.completed", "order.created"]
  }'

Yanıt · 201

{
  "object": "webhook_endpoint",
  "id": "01c2a784-4bcf-43b9-8ac9-ddbad7a25341",
  "url": "https://pos.example.com/loyaltyfy/webhooks",
  "description": null,
  "events": ["transaction.completed", "order.created"],
  "status": "enabled",
  "disabled_reason": null,
  "livemode": false,
  "created_at": "2026-10-06T18:17:32.381+00:00",
  "secret": "whsec_UvjHvXfPk80ITYl_xPeAtskI0WjR8-PS"
}

Ne alırsınız

curl

POST /loyaltyfy/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: Loyaltyfy-Webhooks/1.0
Loyaltyfy-Signature: t=1791310488,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

JSON

{
  "id": "evt_5a1f0c9e2b7d4e3f81a0c6d2",
  "object": "event",
  "type": "order.created",
  "created": 1791310488,
  "livemode": true,
  "data": {
    "object": {
      "object": "order",
      "id": "0c69a81c-0fbc-4333-b26c-789566b9bea4",
      "number": 10,
      "status": "new",
      "table": "7",
      ...
    }
  }
}

data.object, API'nin döndürdüğü nesnenin (işlem, üye, sipariş) olay anındaki halidir. 10 saniye içinde herhangi bir 2xx ile yanıt verin. Uzun süren işleri yanıt verdikten sonra yapın.

İmzayı doğrulayın

Loyaltyfy-Signature bir zaman damgası t ve bir imza v1 içerir: t, nokta ve ham istek gövdesinin, uç noktanızın gizli anahtarıyla hesaplanan HMAC-SHA256 değeri (hex). İmzayı JSON ayrıştırmadan önce, aldığınız baytların tam üzerinden hesaplayın, sabit zamanlı karşılaştırma yapın ve beş dakikadan eski zaman damgalarını reddedin.

Node.js

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string or Buffer, not parsed JSON)
export function verifyLoyaltyfy(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hmac, hashlib, time

def verify_loyaltyfy(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > tolerance:
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Yeniden denemeler

Uç noktanız zamanında 2xx ile yanıt vermezse 1 dakika, 5 dakika, 30 dakika, 2 saat, 6 saat, 12 saat ve 24 saat sonra tekrar deneriz. Art arda 20 başarısız gönderimden sonra uç nokta devre dışı bırakılır ve işletme nedenini panelde görür. Uç noktayı PATCH /v1/webhook_endpoints/{id} ve enabled: true ile yeniden etkinleştirin.

Yeniden denemeler nedeniyle bir olay birden fazla kez gelebilir, olaylar sırasız da gelebilir. Tekrarları atlamak için olayın id değerini, hangisinin daha yeni olduğuna karar vermek için nesnenin kendi zaman damgalarını kullanın.

Uç noktayı test edin

curl

curl -X POST https://loyaltyfy.io/api/v1/webhook_endpoints/01c2a784-4bcf-43b9-8ac9-ddbad7a25341/test \
  -H "Authorization: Bearer sk_test_..."

# { "object": "webhook_test", "delivered": true, "status_code": 200, "error": null }

Olayların tam listesi Olaylar referansında yer alır.