Webhook nhận thông báo
Nhận sự kiện realtime (API key, hạn mức…) qua HTTP POST có ký HMAC, cấu hình tại Dashboard › Thông báo.
Kênh Webhook gửi sự kiện tới hệ thống riêng ngay khi phát sinh, không cần gọi API định kỳ (polling). Với mỗi sự kiện, iNET gửi một HTTP POST (JSON) đến URL đã đăng ký, kèm chữ ký HMAC để xác minh request đúng là từ iNET.
Tạo kênh Webhook
Vào Dashboard › Thông báo (developers.inet.vn/dashboard/notifications), bấm Thêm kênh rồi chọn Webhook. Nhập URL Webhook của endpoint nhận, điền Secret token (tự đặt từ 16 ký tự trở lên, hoặc bấm Ngẫu nhiên để tạo), chọn sự kiện rồi bấm Thêm kênh.

Hình 1: Tạo kênh Webhook.
Lưu ý: Sao chép Secret token trước khi bấm Thêm kênh. Sau khi tạo, Dashboard không hiện lại token; khi sửa kênh, để trống ô này là giữ token cũ, nhập token mới là đổi.
Yêu cầu với endpoint nhận
Endpoint nhận phải là địa chỉ HTTPS công khai, nhận POST application/json, xác minh chữ ký, rồi trả về status code 2xx trong vòng 30 giây. Phản hồi chậm hơn 30 giây, trả status code khác 2xx hoặc trả redirect 3xx đều bị tính là thất bại và iNET sẽ retry.
Cấu trúc payload
Mỗi lần gửi (delivery) đều có chung một cấu trúc cố định; riêng trường data thay đổi theo từng sự kiện:
{
"id": "8f3a1c2e-0b7d-4e9a-9c11-2a6b5d4e7f00",
"event": "api_key.created",
"created_at": "2026-01-15T08:30:00.000Z",
"scope": "personal",
"event_id": "evt_9d4f1a7c2e",
"data": {
"id": "key_a1b2c3d4",
"name": "Production key",
"keyPrefix": "inet_sk_a1b2",
"createdAt": "2026-01-15T08:30:00.000Z"
}
}
| Trường | Ý nghĩa |
|---|---|
id | ID của lần gửi (UUID) — trùng với header X-iNET-Delivery |
event | Tên sự kiện (xem bảng bên dưới) |
created_at | Thời điểm sự kiện phát sinh (ISO 8601) |
scope | "personal" (sự kiện riêng của tài khoản) hoặc "broadcast" (thông báo chung). Chỉ xuất hiện khi có — cần xử lý cả trường hợp vắng trường này |
event_id | ID logic của sự kiện, giống nhau trên mọi kênh trong cùng một lần phát — dùng để chống trùng. Chỉ xuất hiện khi có |
data | Dữ liệu chi tiết, khác nhau theo từng sự kiện |
Danh sách sự kiện
| Sự kiện | Phát sinh khi | Trường chính trong data |
|---|---|---|
api_key.created | Tạo API key mới | id, name, keyPrefix, createdAt |
api_key.revoked | Thu hồi API key | id, name, keyPrefix, revokedAt |
api_key.blocked | API key bị chặn | id, name, keyPrefix, reason, blockedAt |
api_key.unblocked | Bỏ chặn API key | id, name, keyPrefix, unblockedAt |
api_key.expired | API key hết hạn | id, name, keyPrefix, expiredAt |
api_key.expiring_soon | API key sắp hết hạn | apiKeyId, name, expiresAt, daysUntilExpiry, window |
api_key.quota_warning | Sắp chạm hạn mức | apiKeyId, name, used, limit, percent, threshold, date |
api_key.error_rate_high | Tỉ lệ lỗi cao | apiKeyId, name, errorCount, totalCount, errorRate, threshold, hour |
api_key.rate_limit_hit | Chạm giới hạn tần suất | apiKeyId, name, limit, window |
Lưu ý: Ba sự kiện api_key.quota_warning, api_key.error_rate_high và api_key.rate_limit_hit có ngưỡng riêng, chỉnh ở mục Cấu hình ngưỡng trong form khi chọn các sự kiện này.
Mẹo: Ngoài sự kiện API key, kênh còn nhận được các thông báo khác như dịch vụ sắp hết hạn, khuyến mãi, bảo trì. Cấu trúc payload giữ nguyên, chỉ data thay đổi.
Các header trong mỗi request
| Header | Ý nghĩa |
|---|---|
X-iNET-Signature | Chữ ký để xác minh — hãy kiểm tra header này. Giá trị: sha256= + HMAC-SHA256 của raw body |
X-iNET-Event | Tên sự kiện |
X-iNET-Delivery | ID của lần gửi (UUID) — dùng để chống trùng (idempotency) |
X-iNET-Timestamp | Thời điểm gửi (ISO 8601). Chỉ để tham khảo; có thể dùng để tự kiểm tra request có còn hợp lệ không (chống replay, không bắt buộc) |
X-iNET-Original-Delivery | Chỉ xuất hiện khi một lần gửi được gửi lại thủ công (replay): chứa ID của lần gửi gốc |
Xác minh chữ ký
Mỗi request đính kèm header X-iNET-Signature: sha256=<hex>, trong đó hex = HMAC-SHA256(secret, raw body). Tính lại HMAC-SHA256 bằng Secret token của kênh trên đúng raw body, rồi so sánh bằng constant-time comparison. Chép handler phù hợp bên dưới vào project và đặt biến môi trường INET_WEBHOOK_SECRET bằng Secret token của kênh:
Lưu ý quan trọng: Phải tính chữ ký trên raw body — tức là nguyên chuỗi byte nhận được, KHÔNG phải JSON đã parse rồi serialize lại. Lệch một byte là sai chữ ký.
// Next.js — app/api/webhook/route.ts
import { createHmac, timingSafeEqual } from "crypto"
const SECRET = process.env.INET_WEBHOOK_SECRET
export async function POST(req) {
const raw = await req.text() // raw body — KHÔNG dùng req.json()
const sig = req.headers.get("x-inet-signature") ?? ""
const mine = "sha256=" + createHmac("sha256", SECRET).update(raw).digest("hex")
const a = Buffer.from(mine), b = Buffer.from(sig)
if (a.length !== b.length || !timingSafeEqual(a, b))
return new Response("invalid signature", { status: 401 })
const { event, data } = JSON.parse(raw)
// TODO: xử lý event tại đây
return Response.json({ ok: true })
}Chống replay (không bắt buộc): chữ ký không bao gồm timestamp. Nếu cần chống phát lại (replay), hãy chống trùng theo X-iNET-Delivery (xem mục bên dưới) và/hoặc tự kiểm tra X-iNET-Timestamp vẫn còn mới (ví dụ: trong vòng 5 phút).
Retry & chống trùng (idempotency)
Webhook hoạt động theo cơ chế at-least-once: nếu endpoint phản hồi chậm, timeout hoặc lỗi, iNET sẽ retry tối đa 4 lần (tổng cộng 5 lần gửi), khoảng cách tăng dần 60s → 120s → 240s → 480s. Sau 5 lần vẫn thất bại, lần gửi đó bị bỏ. Đôi khi endpoint đã xử lý xong nhưng phản hồi không đến được iNET, nên một sự kiện có thể đến nhiều hơn một lần — cần xử lý idempotent:
- Retry tự động (do timeout/lỗi): iNET giữ nguyên
X-iNET-Delivery(vàbody.id). Hãy lưu lại các ID đã xử lý, gặp lại thì bỏ qua. - Gửi lại thủ công (replay, khi iNET gửi lại theo yêu cầu hỗ trợ): iNET cấp ID mới cho
X-iNET-Delivery/body.id, kèm ID gốc ở headerX-iNET-Original-Delivery. Để chống trùng cho replay, hãy dựa vàoX-iNET-Original-Delivery(hoặcevent_id), không chỉX-iNET-Delivery.
Xử lý idempotent giúp tránh tạo trùng bản ghi, gửi trùng email hay tính sai số liệu.
Lưu ý khi triển khai
- Trả 2xx ngay khi nhận được; chuyển các tác vụ xử lý tốn thời gian sang background để không vượt quá 30 giây.
- URL chỉ chấp nhận các cổng 80, 443, 8080, 8443 — cổng khác bị iNET từ chối ngay (nếu đổi cổng sau khi đăng ký, webhook sẽ lặng lẽ thất bại).
- Endpoint không nên đặt sau lớp đăng nhập hay IP allow-list — webhook không gửi kèm cookie phiên (session), và IP nguồn của iNET có thể thay đổi. Hãy dựa vào chữ ký HMAC để xác thực.
- Không trả redirect 3xx — sẽ bị tính là thất bại.
- Giữ Secret token bí mật; nếu nghi ngờ bị lộ, hãy tạo lại tại trang cấu hình kênh.