Webhook

Ngày cập nhật: 07 tháng 07, 2026
Người cập nhật: VNPT eContract's team

---

Mục đích

Webhook được dùng để VNPT eContract gửi thông báo trạng thái chứng từ sang backend 3rd-party khi phát sinh các sự kiện đã cấu hình. Phía đối tác cần chuẩn bị RESTful API để tiếp nhận và xử lý dữ liệu webhook.

Cấu hình webhook trên website admin

Trên website admin, tạo mới hoặc cập nhật cấu hình webhook với các thông tin sau:

Cấu hình	Mô tả
URL nhận thông báo	Endpoint backend 3rd-party dùng để nhận webhook, ví dụ https://domain-partner.com/api/document/status.
Sự kiện	Chọn một hoặc nhiều sự kiện cần gửi webhook. Các sự kiện thường dùng gồm Hoàn tất chứng từ, Hoàn tất chứng từ hàng loạt, Từ chối chứng từ, Từ chối chứng từ hàng loạt.
Header	Header tùy chỉnh để backend 3rd-party xác thực hoặc định tuyến request, ví dụ Authorization, X-API-Key, X-Webhook-Secret, hoặc X-Tenant-Code.
Body	Mẫu JSON body sẽ được VNPT eContract gửi khi sự kiện xảy ra. Body có thể dùng placeholder như {{DocumentIds}}.

mẹo

Nên dùng header tùy chỉnh khi backend 3rd-party cần xác thực request được gửi từ VNPT eContract. Backend nên kiểm tra các header này trước khi xử lý body webhook.

Mẫu cấu hình trên admin

Với sự kiện Hoàn tất chứng từ và Hoàn tất chứng từ hàng loạt, có thể cấu hình body như sau:

{
    "DocumentIds": "{{DocumentIds}}",
    "Status": {
        "Value": 4,
        "Description": "Completed"
    }
}

Với sự kiện Từ chối chứng từ và Từ chối chứng từ hàng loạt, có thể cấu hình body như sau:

{
    "DocumentIds": "{{DocumentIds}}",
    "Status": {
        "Value": -1,
        "Description": "Rejected"
    }
}

Ví dụ header:

Authorization: Bearer {token}
X-Webhook-Secret: {shared-secret}
X-Tenant-Code: {tenant-code}

cẩn thận

• {{DocumentIds}} sẽ được thay bằng danh sách ID chứng từ liên quan khi webhook được gửi.
• Backend 3rd-party chỉ nên trả về response thành công sau khi đã xác thực và chấp nhận payload để xử lý.
• Nếu cùng một sự kiện có thể được gửi nhiều lần do retry hoặc lỗi mạng, backend 3rd-party nên xử lý webhook theo hướng idempotent dựa trên ID chứng từ và trạng thái.

Yêu cầu API nhận webhook

Phía đối tác xây dựng một RESTful API với các tham số như bên dưới để tiếp nhận và xử lý dữ liệu từ webhook:

• URL endpoint (do đối tác cung cấp), ví dụ: https://domain-partner.com/api/document/status
• HTTP method: POST
• HTTP content-type: application/json
• Authorization: Bearer token (tuỳ chọn nếu cần bảo mật)
• Payload: Dữ liệu sẽ được hệ thống VNPT eContract gửi dưới dạng JSON với cấu trúc như sau

Payload mẫu (hệ thống đối tác sẽ nhận được)

{
    "DocumentNo": "HD.001",
    "DocumentId": "fa07d61e-0fff-41a3-e618-08dad69d1b1b",
    "DocumentStatus": {
        "Value": -1,
        "Description": "Đã bị từ chối"
    },
    "Reason": "Mã chứng từ không đúng quy định",
    "DatetimeNow": "2024/11/06 14:56:50"
}

Mô tả dữ liệu

Key	Type	Description
DocumentId	string	Id chứng từ
DocumentNo	string	Mã chứng từ
DocumentType	string	Loại chứng từ
DocumentStatus	object	Trạng thái chứng từ, tham khảo định nghĩa trạng thái tại Lấy danh sách chứng từ
DocumentIds	string / Array[string]	Danh sách ID chứng từ liên quan được gửi theo body template đã cấu hình.
Reason	string	Lý do hủy chứng từ
BatchProcessId	string	Id lô xử lý chứng từ (trường hợp sự kiện xử lý hàng loạt các quy trình)
BatchImportId	int	Id lô import chứng từ (trường hợp sự kiện hoàn tất tạo lô chứng từ)
DocumentIdInBatchImport	Array[int]	Danh sách Id chứng từ trong lô (trường hợp sự kiện hoàn tất tạo lô chứng từ)
DatetimeNow	Datetime	Thời gian thực hiện

Response mẫu (response cho hệ thống VNPT eContract)

{
  "success": true,
  "messages": "Document status updated successfully."
}