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ệuThêm webhook
POST/v1/webhooks

Thêm webhook

Đăng ký URL nhận thông báo theo sự kiện mẫu hoá đơn và hoá đơn. Secret chỉ trả một lần trong phản hồi này.

MarkdownOpenAPI

#Giới thiệu

API thêm một webhook cho ứng dụng tìm theo header app_id. API key phải thuộc ứng dụng đó. Key hddt_test_ thêm vào sandbox. Key Live thêm vào production.

Phản hồi có secret dạng whsec_. Lưu lại ngay. Các lần gọi API Danh sách webhook sau không trả secret này. Dùng secret để kiểm tra chữ ký trên header X-HDDT-Signature.

#Endpoint

Gửi POST với JSON. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.

URL phải là HTTPS

url nhận thông báo phải bắt đầu bằng https://. Không dùng địa chỉ nội bộ.

#Header

Gửi App ID của ứng dụng cần gắn webhook và API key của ứng dụng đó.

app_idstringBắt buộc

Định danh ứng dụng (UUID). Sao chép App ID trên trang chi tiết ứng dụng (tab Kết nối & bảo mật).

api_keystringBắt buộc

API key đang hiệu lực của ứng dụng có app_id ở trên.

Content-TypestringBắt buộc

application/json.

#Body

Gửi URL và ít nhất một sự kiện. Bỏ trống enabled thì webhook được bật ngay.

urlstringBắt buộc

URL HTTPS nhận POST khi có sự kiện. Ví dụ https://api.cua-ban.vn/webhooks/hddt.

eventsarray of stringBắt buộc

Sự kiện cần nhận. Gửi ít nhất một mã trong bảng Sự kiện đang đăng ký.

enabledbooleanTuỳ chọn

Bật nhận thông báo ngay khi tạo.

true bật

false tạo nhưng chưa gửi

Bỏ trống thì hệ thống dùng true.

#Sự kiện đang đăng ký

Mỗi phần tử của events là một mã dưới đây. all nhận mọi sự kiện còn lại.

MãTrạng thái
allTất cả
template_createdTạo mẫu hoá đơn
template_quantity_approvedDuyệt số lượng mẫu hoá đơn
template_deletedXoá mẫu hoá đơn
invoice_draft_createdTạo nháp hoá đơn
invoice_issuedPhát hành hoá đơn
invoice_signedKý hoá đơn
tax_authority_responseCQT phản hồi
invoice_draft_deletedXoá hoá đơn nháp

#Ví dụ

Thêm webhook sandbox nhận lúc phát hành hoá đơn và lúc cơ quan thuế phản hồi.

cURL
curl -X POST https://sandbox.api.hddt.dev/v1/webhooks \
  -H "app_id: $HDDT_APP_ID" \
  -H "api_key: $HDDT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.cua-ban.vn/webhooks/hddt",
    "events": ["invoice_issued", "tax_authority_response"]
  }'

#Phản hồi

Khi thêm được, API trả 201. secret chỉ có trong phản hồi này. Lưu lại để kiểm tra chữ ký các thông báo sau.

idstringBắt buộc

Định danh webhook, ví dụ wh_8f2a1c9d.

objectstringBắt buộc

Luôn là webhook.

urlstringBắt buộc

URL HTTPS nhận thông báo.

enabledbooleanBắt buộc

true khi webhook đang nhận thông báo, false khi đang tắt.

eventsarray of stringBắt buộc

Các mã trong bảng Sự kiện đang đăng ký.

secretstringBắt buộc

Bí mật ký thông báo, tiền tố whsec_. Chỉ trả khi vừa thêm webhook.

201 Created
{
  "id": "wh_8f2a1c9d",
  "object": "webhook",
  "url": "https://api.cua-ban.vn/webhooks/hddt",
  "enabled": true,
  "events": ["invoice_issued", "tax_authority_response"],
  "secret": "whsec_4f8c2a91b7e64d0c"
}

#Thông báo gửi tới URL

Khi sự kiện trong events xảy ra và enabled là true, hddt.dev gửi POST tới url. Body, chữ ký và cách kiểm tra nằm ở trang Nhận và kiểm tra webhook.

#Mã lỗi

Lỗi xác thực và dữ liệu không hợp lệ trả mã HTTP kèm error.code và error.message.

401 unauthorized—Tuỳ chọn

Thiếu header app_id hoặc api_key; API key sai, đã thu hồi, hoặc không thuộc app_id.

403 forbidden—Tuỳ chọn

Gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live).

404 not_found—Tuỳ chọn

Không có ứng dụng nào khớp app_id.

422 validation_error—Tuỳ chọn

app_id không phải UUID, thiếu url hoặc events, url không phải HTTPS, events rỗng, hoặc có giá trị ngoài all, template_created, template_quantity_approved, template_deleted, invoice_draft_created, invoice_issued, invoice_signed, tax_authority_response, invoice_draft_deleted.

Trước đóDanh sách webhookTiếp theoNhận và kiểm tra
Trang này có hữu ích không?
Cập nhật lần cuối: 10/11/2026

Trên trang này

  • Giới thiệu
  • Endpoint
  • Header
  • Body
  • Sự kiện đang đăng ký
  • Ví dụ
  • Phản hồi
  • Thông báo gửi tới URL
  • Mã lỗi
Đăng nhậpBắt đầu ngay