Tổng quan webhook

Webhook là cách hoadon.pro chủ động gọi tới hệ thống của bạn khi có sự kiện, ví dụ hoá đơn mới về hoặc kết quả kiểm tra thay đổi. Bạn không cần hỏi API liên tục.

Cách hoạt động

sequenceDiagram
  participant H as hoadon.pro
  participant S as Hệ thống của bạn
  H->>S: POST sự kiện kèm Hd-Signature
  S->>S: Xác thực chữ ký và lưu id sự kiện
  S-->>H: 2xx trong thời gian ngắn
  Note over H,S: Nếu không nhận được 2xx, hoadon.pro thử lại

1. Bạn đăng ký điểm nhận (một URL) và chọn các sự kiện cần nhận.
2. Khi sự kiện xảy ra, hoadon.pro gửi yêu cầu POST có nội dung JSON tới URL đó.
3. Hệ thống của bạn xác thực chữ ký, xử lý và trả mã 2xx.
4. Nếu không nhận được 2xx, hoadon.pro thử lại.

Cấu trúc gói tin

Mọi sự kiện có cùng một khung:

{
  "id": "evt_01J9ZQ8K",
  "type": "invoice.created",
  "created_at": "2026-10-15T09:30:12Z",
  "org_id": "org_01J9Z",
  "data": {}
}

Trường	Ý nghĩa
id	Mã duy nhất của sự kiện. Dùng để loại trùng khi nhận lặp.
type	Loại sự kiện, ví dụ invoice.created.
created_at	Thời điểm sự kiện xảy ra, theo RFC 3339.
org_id	Tổ chức mà sự kiện thuộc về.
data	Nội dung riêng của từng loại sự kiện.

Giá trị trong ví dụ là minh hoạ. Nội dung data của từng sự kiện xem ở Sự kiện.

Việc cần làm ở phía bạn

• Xác thực chữ ký của mọi yêu cầu trước khi tin nội dung: Chữ ký và mẫu xác thực.
• Trả 2xx nhanh, xử lý nặng bằng hàng đợi riêng.
• Loại trùng theo id: một sự kiện có thể tới nhiều hơn một lần.
• Dùng HTTPS cho URL nhận.