Sự kiện webhook

NexERP gửi webhook mỗi khi trạng thái hóa đơn điện tử đổi, để bạn khỏi phải hỏi liên tục.

Webhook chỉ là thông báo. Mất sự kiện thì GET vẫn cho đúng trạng thái, vì `GET` là nguồn sự thật.

Điều kiện dùng

Ứng dụng của bạn có địa chỉ nhận webhook và bí mật ký, do NexERP gắn cho bạn.
Địa chỉ nhận chỉ dùng https và không trỏ vào mạng nội bộ.
Sự kiện đi về địa chỉ webhook của quyền tích hợp đang hoạt động tại thời điểm gửi.

Sự kiện

Có một loại duy nhất: invoice.einvoice_status_changed. Mỗi lần einvoice_status của hóa đơn đổi giá trị, NexERP gửi một sự kiện.

Trạng thái ban đầu queued lúc tạo hóa đơn có thể không sinh sự kiện. Hãy dựa vào phản hồi 202 của POST /invoices cho trạng thái đó.

Request NexERP gửi tới bạn

POST <địa chỉ nhận webhook của bạn>, ví dụ POST https://pump.vidu.example/nexerp/webhook. Thân là JSON UTF-8.

{
  "event_id": "5d2a8f1e-3c47-4d4c-8f6e-0b7a1c9e2d33",
  "event_type": "invoice.einvoice_status_changed",
  "occurred_at": "2026-10-22T00:41:40.512345+00:00",
  "invoice": {
    "id": "0b3c5a2e-6f43-4f0e-9a52-6e2f6d6a7c11",
    "external_id": "CN5-P03-V2-20261022-000123",
    "status": "confirmed",
    "sold_at": "2026-10-22",
    "invoice_date": "2026-10-22",
    "einvoice_status": "issued",
    "einvoice": {
      "number": "00000123",
      "serial": "1C26MLB",
      "template": "1",
      "lookup_code": null,
      "issued_at": "2026-10-22T07:41:40+07:00",
      "view_url": null,
      "error": null
    },
    "replaced_by": null,
    "replaces": null
  }
}

Trường	Kiểu	Ý nghĩa
`event_id`	chuỗi UUID	Mã sự kiện, duy nhất. Bằng header `X-Nex-Event-Id`, dùng để loại trùng
`event_type`	chuỗi	Loại sự kiện. Hiện chỉ có `invoice.einvoice_status_changed`
`occurred_at`	thời điểm ISO 8601 (UTC)	Lúc trạng thái đổi
`invoice`	đối tượng	Khối trạng thái hóa đơn, giống hệt kết quả `GET /invoices/{id}`

Các header

Header	Nội dung
`X-Nex-Signature`	`t=<unix>,v1=<hex>`
`X-Nex-Event-Id`	Mã sự kiện, bằng `event_id` trong thân. Dùng để loại trùng
`Content-Type`	`application/json`

Lưu ý

Luôn xác minh chữ ký trước khi xử lý. Cách làm ở bài Xác minh chữ ký.
Thứ tự các sự kiện không được đảm bảo. Đọc einvoice_status trong thân, hoặc gọi GET.