Webhooks

Webhooks cho phép hệ thống của bạn nhận thông báo realtime khi có sự kiện trong XCaphe — thay vì phải polling liên tục.

Webhooks đang trong giai đoạn beta. Liên hệ support@xcaphe.vn để kích hoạt cho tài khoản của bạn.

Cấu hình webhook

Vào Cài đặt → Webhooks → + Thêm endpoint
Điền URL endpoint của bạn (phải là HTTPS)
Chọn các sự kiện muốn nhận
Lưu → XCaphe gửi POST test request để xác nhận

Cấu trúc payload

Mọi webhook event đều có cấu trúc chung:

{
  "event": "order.completed",
  "timestamp": "2025-03-01T08:30:00+07:00",
  "orgId": "uuid",
  "branchId": "uuid",
  "data": {
    // Dữ liệu cụ thể của event
  }
}

Danh sách sự kiện

Đơn hàng

Event	Mô tả
`order.created`	Đơn hàng mới được tạo
`order.confirmed`	Đơn được xác nhận
`order.preparing`	Đơn chuyển sang đang pha chế
`order.ready`	Đơn hoàn thành pha chế, chờ khách
`order.completed`	Đơn hoàn thành, kho đã trừ
`order.cancelled`	Đơn bị huỷ

Thanh toán

Event	Mô tả
`payment.paid`	Thanh toán thành công
`payment.refunded`	Đã hoàn tiền

Kho

Event	Mô tả
`inventory.low_stock`	Nguyên liệu xuống dưới ngưỡng cảnh báo

Xác thực webhook

Mỗi request từ XCaphe có header:

X-XCaphe-Signature: sha256=<hmac>

Verify bằng HMAC-SHA256 với webhook secret (lấy trong dashboard):

import crypto from "crypto";
 
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry policy

Nếu endpoint trả về status code khác 2xx, XCaphe sẽ retry:

Sau 5 phút (lần 1)
Sau 30 phút (lần 2)
Sau 2 giờ (lần 3)

Sau 3 lần thất bại, event được đánh dấu "Failed" và không retry nữa. Bạn có thể trigger lại thủ công trong dashboard.

Đơn hàng Câu hỏi thường gặp