# Nhận và kiểm tra webhook > Chỉ dùng endpoint, field, mã lỗi và ví dụ trong trang này. Không thêm API chưa được mô tả ở đây. Đọ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. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `Content-Type` | string | có | application/json. | | `X-HDDT-Event` | string | có | Mã sự kiện. Trùng với type trong body. Không bao giờ là all. | | `X-HDDT-Signature` | string | có | Chữ 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ó. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Mã thông báo, tiền tố evt_. Dùng để bỏ qua thông báo đã xử lý. | | `object` | string | có | Luôn là event. | | `type` | string | có | Mã sự kiện. Trùng header X-HDDT-Event. | | `created_at` | string | có | Thời điểm gửi, ISO 8601, múi giờ +07:00. | | `data` | object | có | Nộ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. template_created: ```json { "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. template_quantity_approved: ```json { "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. template_deleted: ```json { "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ế. invoice_draft_created: ```json { "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ố. invoice_issued: ```json { "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. invoice_signed: ```json { "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. tax_authority_response: ```json { "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. invoice_draft_deleted: ```json { "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. Nguyên văn body: ```json {"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 đó. Node.js: ```javascript 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. Python: ```python 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: ```php