/v1/webhooksThê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.
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
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ộcAPI key đang hiệu lực của ứng dụng có app_id ở trên.
Content-TypestringBắt buộcapplication/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ộcURL HTTPS nhận POST khi có sự kiện. Ví dụ https://api.cua-ban.vn/webhooks/hddt.
eventsarray of stringBắt buộcSự 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ọnBậ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 |
|---|---|
| all | Tất cả |
| template_created | Tạo mẫu hoá đơn |
| template_quantity_approved | Duyệt số lượng mẫu hoá đơn |
| template_deleted | Xoá mẫu hoá đơn |
| invoice_draft_created | Tạo nháp hoá đơn |
| invoice_issued | Phát hành hoá đơn |
| invoice_signed | Ký hoá đơn |
| tax_authority_response | CQT phản hồi |
| invoice_draft_deleted | Xoá 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 -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ộcLuôn là webhook.
urlstringBắt buộcURL HTTPS nhận thông báo.
enabledbooleanBắt buộctrue khi webhook đang nhận thông báo, false khi đang tắt.
eventsarray of stringBắt buộcCác mã trong bảng Sự kiện đang đăng ký.
secretstringBắt buộcBí mật ký thông báo, tiền tố whsec_. Chỉ trả khi vừa thêm webhook.
{
"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ọnThiế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ọnGử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ọnKhông có ứng dụng nào khớp app_id.
422 validation_error—Tuỳ chọnapp_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.