Вебхуктар

Бірдеңе болғанда HTTPS POST алыңыз: кез келген жерде чек өтті, сыйлық ашылды, үстелден тапсырыс түсті.

Оқиғалар осы мекемеде API арқылы жасалғанның бәрін қамтиды: сіздің интеграцияңыз да, кез келген басқа интеграция да (басқа касса, киоск, жазылу коннекторы). Тек өзіңіз пайдаланатын оқиғаларға жазылыңыз.

Эндпоинт қосу

Әзірлеушілерге → Вебхуктар бөлімінде немесе API арқылы. URL жария HTTPS болуы керек. Қолтаңба құпиясы эндпоинт жасалғанда бір рет қана қайтарылады.

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

Жауап · 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"
}

Сізге не келеді

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 қайтаратын объектінің өзі (транзакция, қатысушы, тапсырыс), оқиға болған сәттегі күйінде. 10 секунд ішінде кез келген 2xx кодымен жауап беріңіз. Ұзақ жұмысты жауап бергеннен кейін орындаңыз.

Қолтаңбаны тексеру

Loyaltyfy-Signature ішінде t уақыт белгісі мен v1 қолтаңбасы бар: бұл t, нүкте және сұраудың өңделмеген денесінен эндпоинт құпиясымен есептелген HMAC-SHA256, hex түрінде. Оны JSON парсингіне дейін, дәл өзіңіз алған байттар бойынша есептеңіз, тұрақты уақытта салыстырыңыз және бес минуттан ескі уақыт белгілерін қабылдамаңыз.

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", ""))

Қайталаулар

Эндпоинтіңіз уақытында 2xx қайтармаса, 1 минуттан, 5 минуттан, 30 минуттан, 2 сағаттан, 6 сағаттан, 12 сағаттан және 24 сағаттан кейін қайталаймыз. Қатарынан 20 сәтсіз жеткізуден кейін эндпоинт өшіріледі, ал мекеме себебін басқару панелінен көреді. Оны PATCH /v1/webhook_endpoints/{id} және enabled: true арқылы қайта қосыңыз.

Қайталаулардың әсерінен бір оқиға бірнеше рет келуі мүмкін, ал оқиғалар ретсіз келуі мүмкін. Қайталанғандарды өткізіп жіберу үшін оқиғаның id мәнін, ал қайсысы жаңа екенін анықтау үшін объектінің өз уақыт белгілерін пайдаланыңыз.

Эндпоинтті тексеру

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 }

Оқиғалардың толық тізімі Оқиғалар анықтамалығында.