Tài liệu API webhook

Bật webhook

Mở Kết nối API: đăng nhập app.pandio.vn bằng tài khoản chủ studio, vào Cấu hình & Quản trị → Kết nối API.
Thêm địa chỉ nhận: đặt tên, chọn loại Chung (JSON chuẩn) hoặc Lark (tin nhắn bot Lark), dán địa chỉ HTTPS công khai. Có thể nhập khóa bí mật để ký từng yêu cầu.
Bật và theo dõi: lịch sử gửi (thành công, thất bại, số lần thử, mã HTTP) hiện ngay trong màn Kết nối API.

Chỉ chấp nhận địa chỉ HTTPS trỏ tới máy chủ công khai; địa chỉ nội bộ (localhost, IP mạng LAN) bị từ chối.

Sự kiện

Sự kiện	Khi nào gửi	Header X-Pandio-Event
`contract.first_deposit`	Hợp đồng nhận tiền cọc đầu tiên (hợp đồng dịch vụ hoặc cho thuê trang phục)	`contract.first_deposit.sddv` `contract.first_deposit.rental`
`review.submitted`	Khách gửi form đánh giá dịch vụ	`review.submitted`

Dữ liệu gửi (loại Chung)

Yêu cầu POST, thân JSON UTF-8. Header kèm theo: X-Pandio-Event, X-Pandio-Delivery (mã lần gửi) và X-Pandio-Signature nếu có khóa bí mật.

{
  "event": "contract.first_deposit",
  "event_id": "sddv-1287-first-deposit",
  "studio_id": 12,
  "contract": {
    "id": 1287, "type": "sddv", "code": "HD-2418",
    "customer_name": "Linh & An", "customer_phone": "09xx xxx xxx",
    "referral_source": "Facebook", "shoot_date": "2026-11-02", "wedding_date": "2026-12-20",
    "contract_type": "Sử dụng dịch vụ", "total_vnd": 25000000,
    "referral_code": null, "notes": "…", "creator": "@Thu Hà (Sale)",
    "creator_role": "sales", "status": "…"
  },
  "text": "Nội dung đã định dạng sẵn để gửi thẳng vào tin nhắn"
}

Với review.submitted, khóa contract được thay bằng review: id, contract_id, contract_code, customer_name, form, average_score, submitted_at và danh sách answers (question, type là score hoặc text, value). Dùng event_id để bỏ qua bản gửi trùng.

Xác thực chữ ký

Khi có khóa bí mật, X-Pandio-Signature có dạng sha256=<hex>: HMAC-SHA256 của nguyên văn thân yêu cầu với khóa bí mật. So sánh bằng hàm an toàn thời gian.

// Node.js
const crypto = require("crypto");
const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-pandio-signature"] || ""));

// PHP
$expected = 'sha256=' . hash_hmac('sha256', file_get_contents('php://input'), $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_PANDIO_SIGNATURE'] ?? '');

Loại Lark dùng cơ chế ký của bot Lark (trường timestamp và sign) thay cho header trên.

Phản hồi và gửi lại

Trả mã HTTP 2xx trong vòng vài giây để báo đã nhận. Nếu lỗi hoặc quá thời gian, Pandio thử lại tối đa 3 lần, cách nhau 30 giây, 2 phút và 5 phút. Pandio không theo chuyển hướng (redirect).

API đọc, ghi dữ liệu cho bên thứ ba chưa mở công khai. Nếu studio cần tích hợp sâu hơn, gọi 1900 1681 hoặc gửi yêu cầu.

Kết nối Pandio với hệ thống của bạn

Bật webhook

Sự kiện

Dữ liệu gửi (loại Chung)

Xác thực chữ ký

Phản hồi và gửi lại