hddt.dev
Tài liệuBảng giáTra cứu

Bắt đầu

  • Tổng quan
  • Bắt đầu nhanh
  • Xác thực
  • Môi trường sandbox
  • Mã lỗi

Ứng dụng

  • GETThông tin ứng dụng
  • PATCHCập nhật ứng dụng

Hoá đơn

  • POSTLấy token
  • GETLấy mẫu hoá đơn
  • GETDanh sách mẫu đã đăng ký
  • GETHạn mức hoá đơn
  • POSTTạo mẫu hoá đơn
  • POSTDuyệt số lượng hoá đơn
  • DELETEXoá mẫu chưa duyệt
  • POSTTạo hoá đơn
  • GETDanh sách hoá đơn
  • POSTKý hoá đơn nháp
  • GETTải hoá đơn PDF/XML
  • DELETEXoá hoá đơn nháp

Tra cứu

  • GETTra cứu mã số thuế

Webhook

  • GETDanh sách webhook
  • POSTThêm webhook
  • POSTNhận và kiểm tra
Trang chủTài liệuNhận và kiểm tra webhook

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.

Markdown

#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ộc

application/json.

X-HDDT-EventstringBắt buộc

Mã sự kiện. Trùng với type trong body. Không bao giờ là all.

X-HDDT-SignaturestringBắt buộ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ó.

idstringBắt buộc

Mã thông báo, tiền tố evt_. Dùng để bỏ qua thông báo đã xử lý.

objectstringBắt buộc

Luôn là event.

typestringBắt buộc

Mã sự kiện. Trùng header X-HDDT-Event.

created_atstringBắt buộc

Thời điểm gửi, ISO 8601, múi giờ +07:00.

dataobjectBắt buộ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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{"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
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
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
$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");
}
Trước đóThêm webhook
Trang này có hữu ích không?
Cập nhật lần cuối: 09/11/2026

Trên trang này

  • Giới thiệu
  • Header
  • Body
  • Tạo mẫu hoá đơn
  • Duyệt số lượng mẫu
  • Xoá mẫu hoá đơn
  • Tạo nháp hoá đơn
  • Phát hành hoá đơn
  • Ký hoá đơn
  • CQT phản hồi
  • Xoá hoá đơn nháp
  • Chữ ký
  • Kiểm tra
  • Node.js
  • Python
  • PHP
Đăng nhậpBắt đầu ngay