# 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