Webhook

Updated date: 07/07/2026
Updated by: VNPT eContract's team

---

Purpose

Webhook is used for VNPT eContract to send document status notifications to a 3rd-party backend when configured events occur. The partner needs to prepare a RESTful API endpoint to receive and process webhook data.

Configure webhook on the admin website

On the admin website, create or update a webhook configuration with the following information:

Configuration	Description
Notification URL	The 3rd-party backend endpoint that receives the webhook, for example https://domain-partner.com/api/document/status.
Events	Select one or more events that should trigger the webhook. Common events include Document completed, Batch document completed, Document rejected, and Batch document rejected.
Header	Optional custom headers used by the 3rd-party backend for authentication or routing, for example Authorization, X-API-Key, X-Webhook-Secret, or X-Tenant-Code.
Body	JSON body template sent by VNPT eContract when the selected event occurs. The template can use placeholders such as {{DocumentIds}}.

tip

Use custom headers when the 3rd-party backend needs to verify that the request is sent from VNPT eContract. The backend should validate these headers before processing the webhook body.

Admin configuration sample

For Document completed and Batch document completed events, use a body template similar to:

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

For Document rejected and Batch document rejected events, use a body template similar to:

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

Header example:

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

caution

• {{DocumentIds}} is replaced by the list of related document IDs when the webhook is sent.
• The 3rd-party backend should return a successful response only after the payload is validated and accepted for processing.
• If the same event can be sent more than once because of retry or network issues, the 3rd-party backend should process the webhook idempotently by document ID and status.

Receiver API requirements

The partner has developed a RESTful API with the following parameters to receive and process data from the webhook:

• URL endpoint (provided by the partner), example: https://domain-partner.com/api/document/status
• HTTP method: POST
• HTTP content-type: application/json
• Authorization: Bearer token (optional if security is needed)
• Payload: Data will be sent by the VNPT eContract system in JSON format with the following structure:

Payload sample (the partner's system will receive)

{
    "DocumentNo": "HD.001",
    "DocumentId": "fa07d61e-0fff-41a3-e618-08dad69d1b1b",
    "DocumentStatus": {
        "Value": -1,
        "Description": "Rejected"
    },
    "Reason": "Document no is incorrect format",
    "DatetimeNow": "2024/11/06 14:56:50"
}

Data description

Key	Type	Description
DocumentId	string	Id of document
DocumentNo	string	Code of document
DocumentType	string	Type of document
DocumentStatus	object	Status of document, reference Get list of documents
DocumentIds	string / Array[string]	List of related document IDs sent by the configured webhook body template.
Reason	string	Reason cancel document
BatchProcessId	string	Document batch processing Id (in case of an event processing multiple workflows)
BatchImportId	int	Document import batch Id (in case of an event completing batch creation of documents)
DocumentIdInBatchImport	Array[int]	List of document Id within the batch (in case of an event completing batch creation of documents)
DatetimeNow	Datetime	Execute time

Response sample (response to the VNPT eContract system)

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