API and Webhook API and Webhook

REST API (server-to-server) và Webhook cho tích hợp backend: đọc/ghi user, điểm, tier, leaderboard; nhận sự kiện khi đổi thưởng, thay đổi tier.

REST API (server-to-server)

• Xác thực: API Key (Bearer). Lấy từ Client Admin → API Keys.
• Định danh user: external_id (id user trên hệ thống của bạn).
• Bạn có thể đọc điểm, hạng (tier), leaderboard của user; tạo/xác định user (Identify) nếu chưa có. Định dạng request/response và URL cụ thể do bên vận hành cung cấp trong tài liệu tích hợp dành cho đối tác.

Webhook

Engine gửi HTTP request (POST) tới URL mà bạn cấu hình khi có sự kiện (vd. reward_redeemed, tier_change). Payload thường là JSON chứa id redemption, user, reward, trạng thái. Xác thực: có thể dùng HMAC (signature trong header); Engine retry tối đa 3 lần nếu endpoint trả lỗi hoặc timeout.

Redemption callback (đổi thưởng)

Khi user đổi điểm lấy reward, Engine gửi webhook tới URL của bạn. Bạn xử lý (gửi quà, kích hoạt mã) và trả 2xx. Sau đó gọi Callback URL (Fulfillment API) để cập nhật trạng thái fulfilled / failed. Thông tin sau khớp với màn hình Client Admin → Information for third parties (khi bên thứ ba trả voucher hoặc báo trạng thái).

Callback URL: <BASE_URL>/v1/admin/rewards/redemptions/{redemption_id} — thay {redemption_id} bằng redemption_id nhận từ body webhook. Method: PATCH. Xác thực: header Authorization: Bearer <api_key> (tạo API Key trong Client Admin → API Keys, chia sẻ cho bên thứ ba; key chỉ hiển thị một lần khi tạo).

Bạn cần làm gì (checklist cho Developer)

1. Lấy API Key — Client Admin → API Keys. Dùng cho mọi request tới Engine (Identify, đọc điểm, gọi callback).
2. Cấu hình URL webhook — Client Admin → mục Webhook / cài đặt. Nhập URL endpoint backend của bạn (vd. https://api.tenant.com/webhooks/gamify). Lưu secret (nếu có) để verify chữ ký.
3. Implement endpoint nhận webhook — Một route POST nhận JSON, parse body, trả 200 OK trong vài giây (nếu xử lý lâu thì queue rồi trả 200 ngay). Nếu không trả 2xx, Engine có thể retry.
4. (Khuyến nghị) Verify chữ ký — Request có header X-GamifyEngine-Signature và X-GamifyEngine-Timestamp. Engine ký chuỗi timestamp + '.' + bodyRaw (body là raw string của request, chưa parse JSON). Bạn dùng cùng cách: lấy raw body và timestamp từ header, nối timestamp + '.' + bodyRaw, HMAC-SHA256 với secret, so sánh với X-GamifyEngine-Signature. Xem mục “Verify HMAC” bên dưới.
5. Fulfill — Từ payload lấy external_user_id, redemption_id, reward → thực hiện cấp quà (gửi voucher, nạp credit, ghi log).
6. Gọi API callback — Sau khi fulfill xong (hoặc thất bại), gọi PATCH <BASE_URL>/v1/admin/rewards/redemptions/{redemption_id} với header Authorization: Bearer <api_key>. Body: xem mục “Ví dụ body khi gọi API callback” bên dưới. URL đầy đủ và API Key cũng có trong Client Admin (Information for third parties).

Ví dụ payload webhook (bạn sẽ nhận)

Engine gửi POST tới URL của bạn với body JSON dạng sau. Dùng redemption_id khi gọi API callback sau này.

{
  "event": "reward_redeemed",
  "redemption_id": "e6b49abc-c19e-4c39-b27d-19f22fb0bdae",
  "user_id": "57b96ba1-1eb9-458f-8126-34b6d54292e7",
  "external_user_id": "usr_abc123",
  "reward_id": "084d33ab-db85-4210-8293-011fa5c35800",
  "reward_type": "bonus_credit",
  "reward_value": 10,
  "points_spent": 10000,
  "reward": {
    "id": "084d33ab-db85-4210-8293-011fa5c35800",
    "name": "Voucher 10K",
    "type": "bonus_credit",
    "fulfillmentData": {}
  },
  "timestamp": "2026-03-01T04:11:00.763Z"
}

Headers: Content-Type: application/json, X-GamifyEngine-Signature, X-GamifyEngine-Timestamp (dùng để verify).

Verify chữ ký HMAC

Format: Engine gửi X-GamifyEngine-Timestamp (giá trị timestamp nguyên bản, ví dụ Unix seconds hoặc chuỗi do Engine quy định) và X-GamifyEngine-Signature = HMAC-SHA256(timestamp + '.' + bodyRaw, secret). bodyRaw phải là raw body của HTTP request (chuỗi byte/string gốc), không phải JSON đã parse rồi stringify lại (vì thứ tự key có thể đổi). Trong Express, mặc định express.json() đã parse body nên bạn mất raw — cần dùng middleware lưu raw body (vd. express.raw({ type: 'application/json' }) cho route webhook) hoặc đọc raw từ stream trước khi parse.

Ví dụ code backend (Node.js / Express)

Endpoint nhận webhook: (lưu raw body để verify), parse body, verify signature, fulfill, trả 200. Sau đó có thể gọi API callback với redemption_id và status / fulfilled_at / fulfillment_data.

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.GAMIFY_WEBHOOK_SECRET; // secret cấu hình trong Client Admin

// Verify chữ ký (nếu có secret)
function verifySignature(bodyRaw, signature, timestamp) {
  if (!WEBHOOK_SECRET) return true;
  const payload = timestamp + '.' + bodyRaw;
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post('/webhooks/gamify', (req, res) => {
  const rawBody = JSON.stringify(req.body);
  const sig = req.headers['x-gamifyengine-signature'];
  const ts = req.headers['x-gamifyengine-timestamp'];
  if (!verifySignature(rawBody, sig, ts)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, redemption_id, external_user_id, reward, points_spent } = req.body;
  if (event !== 'reward_redeemed') {
    return res.status(200).json({ ok: true });
  }

  // Fulfill: gửi voucher / nạp credit / ...
  yourFulfillService.fulfill({
    redemptionId: redemption_id,
    externalUserId: external_user_id,
    rewardName: reward?.name,
    rewardType: reward?.type,
    pointsSpent: points_spent,
  })
    .then((result) => {
      // (Tuỳ chọn) Gọi API callback để cập nhật fulfilled
      // await updateRedemptionFulfillment(redemption_id, { status: 'fulfilled', fulfilled_at: new Date().toISOString(), fulfillment_data: { code: result.voucherCode } });
      res.status(200).json({ ok: true });
    })
    .catch((err) => {
      // Trả 200 để Engine không retry ngay; có thể gọi callback status: 'failed'
      res.status(200).json({ ok: true, note: 'fulfill queued or failed' });
    });
});

yourFulfillService.fulfill(...) là logic của bạn (gửi email mã voucher, cộng credit vào tài khoản user, v.v.). Sau khi fulfill xong, gọi API callback (URL và format do operator cung cấp) với redemption_id, status: 'fulfilled' hoặc 'failed', fulfilled_at, fulfillment_data (vd. { "code": "VOUCHER-ABC123" }).

Ví dụ body khi gọi API callback (sau khi fulfill)

Gửi PATCH tới <BASE_URL>/v1/admin/rewards/redemptions/{redemption_id} với header Authorization: Bearer <API_KEY>, Content-Type: application/json. Body mẫu (chia sẻ với đối tác):

Thành công (có mã voucher):

{
  "status": "fulfilled",
  "fulfilled_at": "2026-02-24T15:00:00Z",
  "fulfillment_data": { "code": "VOUCHER-ABC123" }
}

Thất bại:

{ "status": "failed", "fulfillment_data": { "reason": "Out of stock" } }

redemption_id lấy từ webhook body (field redemption_id).

Mã lỗi thường gặp

Khi gọi API hoặc nhận webhook, có thể gặp các mã sau. Xử lý ngắn gọn:

Mã	Ý nghĩa	Cách xử lý
AUTH_MISSING_KEY	Thiếu API Key	Gửi header Authorization: Bearer <api_key>.
AUTH_INVALID_KEY	API Key sai hoặc đã thu hồi	Kiểm tra key, tạo key mới trong Client Admin → API Keys nếu cần.
USER_NOT_FOUND	User chưa tồn tại	Gọi Identify (POST /v1/users với externalId) trước khi đọc điểm/tier hoặc gửi event.
TENANT_QUERY_MISMATCH	Tham số tenant không khớp API Key	Đảm bảo query tenant (hoặc header) trùng với tenant của API Key.
EVENT_TYPE_NOT_DECLARED	Event type chưa được khai báo	Tạo event type trong Client Admin → Event Types trước khi gửi event.
CORS_NOT_ALLOWED_FOR_TENANT	Origin không nằm trong CORS của tenant	Thêm origin (URL frontend) vào Client Admin → Settings → CORS (Allowed origins).

{
  "event": "reward_redeemed",
  "redemption_id": "e6b49abc-c19e-4c39-b27d-19f22fb0bdae",
  "user_id": "57b96ba1-1eb9-458f-8126-34b6d54292e7",
  "external_user_id": "usr_abc123",
  "reward_id": "084d33ab-db85-4210-8293-011fa5c35800",
  "reward_type": "bonus_credit",
  "reward_value": 10,
  "points_spent": 10000,
  "reward": {
    "id": "084d33ab-db85-4210-8293-011fa5c35800",
    "name": "Voucher 10K",
    "type": "bonus_credit",
    "fulfillmentData": {}
  },
  "timestamp": "2026-03-01T04:11:00.763Z"
}

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.GAMIFY_WEBHOOK_SECRET;

function verifySignature(bodyRaw, signature, timestamp) {
  if (!WEBHOOK_SECRET) return true;
  const payload = timestamp + '.' + bodyRaw;
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post('/webhooks/gamify', (req, res) => {
  const rawBody = JSON.stringify(req.body);
  const sig = req.headers['x-gamifyengine-signature'];
  const ts = req.headers['x-gamifyengine-timestamp'];
  if (!verifySignature(rawBody, sig, ts)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, redemption_id, external_user_id, reward, points_spent } = req.body;
  if (event !== 'reward_redeemed') {
    return res.status(200).json({ ok: true });
  }

  yourFulfillService.fulfill({
    redemptionId: redemption_id,
    externalUserId: external_user_id,
    rewardName: reward?.name,
    rewardType: reward?.type,
    pointsSpent: points_spent,
  })
    .then((result) => {
      res.status(200).json({ ok: true });
    })
    .catch((err) => {
      res.status(200).json({ ok: true, note: 'fulfill queued or failed' });
    });
});

{
  "status": "fulfilled",
  "fulfilled_at": "2026-02-24T15:00:00Z",
  "fulfillment_data": { "code": "VOUCHER-ABC123" }
}

{ "status": "failed", "fulfillment_data": { "reason": "Out of stock" } }