Khác
Webhook
Webhook báo cho hệ thống của bạn khi smartlink thay đổi, để bạn không phải gọi API liên tục. Khai URL nhận tại Cài đặt → Tích hợp; URL phải dùng https:// và là địa chỉ công khai. Webhook không bắt buộc.
Sự kiện
| event | Khi nào | data |
|---|---|---|
| link.created | Smartlink được tạo (trên web hoặc qua API). | Object smartlink |
| link.updated | Smartlink được sửa. | Object smartlink |
| link.deleted | Smartlink bị xoá. | { "id", "slug" } |
| link.ready | Smartlink lên lịch đã phát hành. | Object smartlink |
| webhook.test | Bấm Gửi thử trên trang quản trị. | { "message" } |
Request KICK gửi
KICK gửi POST với body JSON:
Body
{
"event": "link.ready",
"created_at": "2026-10-20T13:00:05Z",
"workspace_id": "01a0f1c2-…",
"data": { "id": "…", "url": "…", "status": "public", "targets": [ … ], … }
}| Header | Mô tả |
|---|---|
| X-Smartlink-Event | Tên sự kiện, giống trường event. |
| X-Smartlink-Delivery | Mã lần gửi, không đổi khi gửi lại. Dùng để bỏ trùng. |
| X-Smartlink-Signature | t=<unix>,v1=<hex>, xem bên dưới. |
| User-Agent | KICK-Smartlink-Webhook/1 |
Kiểm chữ ký
Mỗi URL có một secret (whsec_…) tại Cài đặt → Tích hợp. v1 là HMAC-SHA256 của chuỗi <t>.<body gốc> với khoá là secret, dạng hex. Tính trên body gốc, trước khi parse JSON, và từ chối request có t lệch quá 5 phút để chống gửi lại.
Kiểm chữ ký
import crypto from "node:crypto";
import express from "express";
const app = express();
// Cần body gốc (chưa parse) để tính chữ ký.
app.post("/webhooks/kick", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("X-Smartlink-Signature") ?? "";
const [t, v1] = header.replace("t=", "").split(",v1=");
const expected = crypto
.createHmac("sha256", process.env.KICK_WEBHOOK_SECRET)
.update(`${t}.${req.body}`)
.digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= 300;
const valid = v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
if (!fresh || !valid) return res.sendStatus(400);
const event = JSON.parse(req.body);
// Trả 2xx ngay, xử lý event sau (hàng đợi), bỏ trùng theo X-Smartlink-Delivery.
res.sendStatus(200);
});Phản hồi và thử lại
- Trả mã
2xxtrong vòng 10 giây để báo đã nhận. KICK không theo redirect. - Nếu lỗi, KICK gửi lại sau 1 phút, 5 phút, 30 phút, 2 giờ, 6 giờ, 12 giờ và 24 giờ (tổng cộng tối đa 8 lần), rồi dừng.
- Một sự kiện có thể tới nhiều lần và không theo thứ tự. Bỏ trùng theo X-Smartlink-Delivery.
- Nên trả 2xx ngay rồi xử lý sau, để không bị tính là quá thời gian.
Link by KICK