Nhận và kiểm tra webhook
Đọc thông báo hddt.dev gửi tới URL của bạn, xem dữ liệu từng sự kiện và kiểm tra chữ ký HMAC-SHA256.
Giới thiệu
Khi một sự kiện đã đăng ký xảy ra và webhook đang bật, hddt.dev gửi POST tới URL của bạn. Thông báo này không gửi API key. Bạn dùng secret nhận lúc thêm webhook để kiểm tra chữ ký.
Đọc nguyên văn body trước khi parse JSON. Chữ ký tính trên đúng chuỗi byte đó. Parse rồi stringify lại sẽ làm chữ ký không khớp.
all chỉ dùng khi đăng ký. Thông báo gửi đi luôn có type là một sự kiện cụ thể.
Request chờ tối đa 3 giây. Hệ thống không đọc body phản hồi và không gửi lại nếu URL lỗi hoặc quá hạn.
Header
Ba header này có trên mọi thông báo.
Content-TypestringBắt buộcapplication/json.
X-HDDT-EventstringBắt buộcMã sự kiện. Trùng với type trong body. Không bao giờ là all.
X-HDDT-SignaturestringBắt buộcChữ ký, dạng sha256= rồi 64 ký tự hex. HMAC-SHA256 của nguyên văn body, khoá là secret.
Body
Body là một JSON. Các trường dưới đây luôn có.
idstringBắt buộcMã thông báo, tiền tố evt_. Dùng để bỏ qua thông báo đã xử lý.
objectstringBắt buộcLuôn là event.
typestringBắt buộcMã sự kiện. Trùng header X-HDDT-Event.
created_atstringBắt buộcThời điểm gửi, ISO 8601, múi giờ +07:00.
dataobjectBắt buộcNội dung của sự kiện. Mỗi type có một body mẫu ở các mục bên dưới.
Tạo mẫu hoá đơn
type là template_created. data là mẫu vừa tạo. published là false cho đến khi mẫu được duyệt số lượng.
{
"id": "evt_91ab30c1",
"object": "event",
"type": "template_created",
"created_at": "2026-11-09T15:41:00+07:00",
"data": {
"id": "15899",
"object": "invoice_template_registration",
"template_id": "1C26TTV",
"form": "1",
"serial": "C26TTV",
"published": false
}
}Duyệt số lượng mẫu hoá đơn
type là template_quantity_approved. data là mẫu sau khi được cấp số lượng. published là true.
{
"id": "evt_91ab30c3",
"object": "event",
"type": "template_quantity_approved",
"created_at": "2026-11-09T15:41:00+07:00",
"data": {
"id": "13362",
"object": "invoice_template_registration",
"template_id": "1C26TDV",
"form": "1",
"serial": "C26TDV",
"year": 2026,
"quantity": 10,
"used": 0,
"remaining": 10,
"published": true
}
}Xoá mẫu hoá đơn
type là template_deleted. data là mẫu vừa xoá. deleted luôn là true.
{
"id": "evt_91ab30c4",
"object": "event",
"type": "template_deleted",
"created_at": "2026-11-09T15:41:00+07:00",
"data": {
"id": "15899",
"object": "invoice_template_registration",
"deleted": true
}
}Tạo nháp hoá đơn
type là invoice_draft_created. data là hoá đơn nháp. status là draft. number và tax_authority_code là null khi chưa có số và chưa có mã cơ quan thuế.
{
"id": "evt_91ab30c5",
"object": "event",
"type": "invoice_draft_created",
"created_at": "2026-11-09T15:41:00+07:00",
"data": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"object": "invoice",
"status": "draft",
"template_id": "1C26TAA",
"number": null,
"tax_authority_code": null,
"total_amount": 1100000,
"created_at": "2026-11-09T15:40:12+07:00"
}
}Phát hành hoá đơn
type là invoice_issued. data là hoá đơn vừa phát hành. status là issued. number đủ 8 chữ số.
{
"id": "evt_91ab30c2",
"object": "event",
"type": "invoice_issued",
"created_at": "2026-11-09T15:41:00+07:00",
"data": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"object": "invoice",
"status": "issued",
"template_id": "1C26TAA",
"number": "00000125",
"tax_authority_code": null,
"total_amount": 1100000,
"created_at": "2026-11-09T15:40:12+07:00"
}
}Ký hoá đơn
type là invoice_signed. data là hoá đơn vừa ký. status là signed.
{
"id": "evt_91ab30c6",
"object": "event",
"type": "invoice_signed",
"created_at": "2026-11-09T15:41:00+07:00",
"data": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"object": "invoice",
"status": "signed",
"template_id": "1C26TAA",
"number": null,
"tax_authority_code": null,
"total_amount": 1100000,
"created_at": "2026-11-09T15:40:12+07:00"
}
}CQT phản hồi
type là tax_authority_response. data.id là mã hoá đơn. status là mã trạng thái cơ quan thuế. status_label là câu tiếng Việt của mã đó. note là ghi chú, chuỗi rỗng khi không có.
1 nháp
2 lỗi ký
3 chưa gửi cơ quan thuế
4 đã cấp mã hoặc đã tiếp nhận
5 cơ quan thuế chưa phản hồi
6 không đủ điều kiện cấp mã hoặc tiếp nhận
7 mẫu 04/SS chưa tạo tờ khai
8 mẫu 04/SS, cơ quan thuế chưa tiếp nhận
9 mẫu 04/SS, cơ quan thuế đã phê duyệt
{
"id": "evt_91ab30c7",
"object": "event",
"type": "tax_authority_response",
"created_at": "2026-11-09T15:41:00+07:00",
"data": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"object": "tax_authority_response",
"tax_authority_code": "007865BA205F284530AA353E42B75820B9",
"status": 4,
"status_label": "Đã cấp mã hoặc đã tiếp nhận",
"note": ""
}
}Xoá hoá đơn nháp
type là invoice_draft_deleted. data là hoá đơn nháp vừa xoá. deleted luôn là true.
{
"id": "evt_91ab30c8",
"object": "event",
"type": "invoice_draft_deleted",
"created_at": "2026-11-09T15:41:00+07:00",
"data": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"object": "invoice",
"status": "draft",
"template_id": "1C26TAA",
"number": null,
"tax_authority_code": null,
"total_amount": 1100000,
"created_at": "2026-11-09T15:40:12+07:00",
"deleted": true
}
}Chữ ký
Khoá HMAC là nguyên secret, gồm tiền tố whsec_. Dữ liệu ký là nguyên văn body, mã UTF-8. Thuật toán là SHA-256. Kết quả viết thường, dạng hex, rồi ghép sau sha256=.
Với secret whsec_4f8c2a91b7e64d0c và chuỗi body bên dưới, header đúng là X-HDDT-Signature: sha256=f081d4627f881b9670d94176855760d44cb6c2e40f24aa686a6459e8750d1fee.
{"id":"evt_91ab30c2","object":"event","type":"invoice_issued","created_at":"2026-11-09T15:41:00+07:00","data":{"id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","object":"invoice","status":"issued","template_id":"1C26TAA","number":"00000125","tax_authority_code":null,"total_amount":1100000,"created_at":"2026-11-09T15:40:12+07:00"}}Kiểm tra
Tính lại chữ ký từ secret và nguyên văn body. So sánh với header bằng hàm so sánh không phụ thuộc thời gian. Sau đó kiểm tra type trùng X-HDDT-Event, rồi mới dùng data.
Từ chối khi thiếu header, chữ ký sai, hoặc type không khớp. Không xử lý data trước khi chữ ký đúng.
Node.js
rawBody là Buffer hoặc chuỗi đúng byte nhận được. Nếu framework đã parse JSON, hãy lấy bản raw trước bước đó.
const crypto = require("crypto");
function signatureOk(rawBody, signature, secret) {
const digest = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const expected = Buffer.from("sha256=" + digest);
const actual = Buffer.from(signature ?? "");
if (expected.length !== actual.length) return false;
return crypto.timingSafeEqual(expected, actual);
}
const secret = process.env.HDDT_WEBHOOK_SECRET;
const signature = headers["x-hddt-signature"];
if (!signatureOk(rawBody, signature, secret)) {
throw new Error("Chữ ký webhook không đúng");
}
const event = JSON.parse(rawBody);
if (event.type !== headers["x-hddt-event"]) {
throw new Error("type không khớp X-HDDT-Event");
}Python
raw_body là bytes của body, chưa json.loads.
import hmac
import hashlib
import json
import os
def signature_ok(raw_body: bytes, signature: str, secret: str) -> bool:
digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
expected = "sha256=" + digest
return hmac.compare_digest(expected, signature or "")
secret = os.environ["HDDT_WEBHOOK_SECRET"]
signature = headers.get("X-HDDT-Signature", "")
if not signature_ok(raw_body, signature, secret):
raise ValueError("Chữ ký webhook không đúng")
event = json.loads(raw_body)
if event["type"] != headers.get("X-HDDT-Event"):
raise ValueError("type không khớp X-HDDT-Event")PHP
php://input là nguyên văn body. Đọc một lần rồi vừa kiểm tra chữ ký vừa json_decode.
<?php
$rawBody = file_get_contents("php://input");
$secret = getenv("HDDT_WEBHOOK_SECRET");
$signature = $_SERVER["HTTP_X_HDDT_SIGNATURE"] ?? "";
$digest = hash_hmac("sha256", $rawBody, $secret);
$expected = "sha256=" . $digest;
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit("Chữ ký webhook không đúng");
}
$event = json_decode($rawBody, true);
$eventName = $_SERVER["HTTP_X_HDDT_EVENT"] ?? "";
if (!is_array($event) || ($event["type"] ?? "") !== $eventName) {
http_response_code(401);
exit("type không khớp X-HDDT-Event");
}