# Thêm 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. `POST /v1/webhooks` Đă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:** 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 đó. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `app_id` | string | 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_key` | string | có | API key đang hiệu lực của ứng dụng có app_id ở trên. | | `Content-Type` | string | 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. Vị trí: body JSON. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `url` | string | có | URL HTTPS nhận POST khi có sự kiện. Ví dụ https://api.cua-ban.vn/webhooks/hddt. | | `events` | array of string | 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ý. | | `enabled` | boolean | không | 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 | | --- | --- | | `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: ```bash 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. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `id` | string | có | Định danh webhook, ví dụ wh_8f2a1c9d. | | `object` | string | có | Luôn là webhook. | | `url` | string | có | URL HTTPS nhận thông báo. | | `enabled` | boolean | có | true khi webhook đang nhận thông báo, false khi đang tắt. | | `events` | array of string | có | Các mã trong bảng Sự kiện đang đăng ký. | | `secret` | string | có | Bí mật ký thông báo, tiền tố whsec_. Chỉ trả khi vừa thêm webhook. | 201 Created: ```json { "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. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | 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` | — | không | 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` | — | không | Không có ứng dụng nào khớp app_id. | | `422 validation_error` | — | không | 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. | Trang HTML: /docs/webhooks/create Cập nhật: 10/11/2026