Webhook

Khi hồ sơ chuyển sang trạng thái quan trọng, hệ thống gửi POST tới URL webhook của bạn. Webhook có chữ ký HMAC, cơ chế retry và khoá idempotency.

Partner không tự đăng ký webhook qua API. Gửi đội ngũ econtractid URL endpoint HTTPS + danh sách event; quản trị viên tạo subscription và cấp HMAC secret (chỉ hiện 1 lần). Đổi URL hoặc event sau này cũng qua quản trị viên.

Luồng gửi

Headers

Header	Giá trị	Mô tả
`X-Webhook-Event`	`document.completed`	Loại event
`X-Webhook-Signature`	`sha256=<hex>`	HMAC-SHA256 của raw body với webhook secret
`X-Webhook-Id`	`evt_<uuid>`	ID event duy nhất, dùng để chống xử lý trùng. Event test có tiền tố `evt_test_`
`User-Agent`	`eContract-Webhook/1.0`	—

Mọi payload dùng chung envelope:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "document.completed",
  "createdAt": "2026-05-16T17:58:12.345Z",
  "data": { }
}

Webhook payload không có envelope {statusCode, data, timestamp} như response REST — gửi raw object.

Event và payload

Nhóm	Event	Dùng để
document	`document.completed` · `document.rejected`	Đồng bộ trạng thái hồ sơ, lấy file đã ký
notification	`notification.task_assigned_internal` · `notification.task_assigned_external` · `notification.task_completed` · `notification.task_rejected` · `notification.process_finished`	Tự gửi thông báo cho người tham gia theo từng bước
test	`webhook.test`	Kiểm tra endpoint và chữ ký

Danh mục event

Mỗi event gửi khi nào, không gửi khi nào, thứ tự trong một quy trình.

Payload tham chiếu

Từng trường của data, ví dụ JSON, và block relatedParties.

Payload — `webhook.test`

Event kiểm thử kết nối, bắn khi quản trị viên bấm Test hoặc khi bạn gọi API ở mục dưới. Dùng để nghiệm thu endpoint: URL, TLS, secret, và bạn có trả 2xx không.

{
  "id": "evt_test_770e8400-e29b-41d4-a716-446655440000",
  "type": "webhook.test",
  "createdAt": "2026-05-16T10:00:00.000Z",
  "data": {
    "message": "This is a test ping from eContract webhook system.",
    "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
    "triggeredBy": "super_admin",
    "metadata": {}
  }
}

Khác biệt so với event thật

	`webhook.test`	`document.` / `notification.`
Đích đến	Đúng 1 subscription	Fanout tới mọi subscription khớp event
Lọc theo danh sách event	Bỏ qua	Có lọc
Retry	Không — gửi 1 lần	6 lần theo lịch retry
Redirect (`301/302`)	Không đi theo	Không đi theo
Prefix event id	`evt_test_`	`evt_`

Tự bắn ping qua API

Hệ thống gửi webhook.test tới webhook đã đăng ký của tổ chức bạn — giống hệt khi quản trị viên bấm Test.

curl -X POST 'https://api.econtractid.com/api/integration/webhooks/test' \
  -H 'X-API-Key: econtract_a1b2c3d4...'

Dùng API Key theo tổ chức (đã gắn người dùng). Key toàn cục dành cho partner-login, gọi vào đây sẽ nhận 401.

{
  "statusCode": 200,
  "data": {
    "total": 1,
    "results": [
      {
        "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
        "url": "https://partner.example.com/webhooks/econtract",
        "httpStatus": 200,
        "latencyMs": 143,
        "requestPayload": { },
        "requestHeaders": { },
        "responseBody": "ok",
        "success": true
      }
    ]
  }
}

requestPayload / requestHeaders là đúng những gì đã gửi, dùng để đối chiếu khi chữ ký lệch. httpStatus: 0 = không kết nối được hoặc quá 10 giây.

HTTP	Nguyên nhân
`403`	Gọi bằng access token — endpoint này chỉ nhận `X-API-Key`
`400`	API Key toàn cục, không gắn tổ chức cụ thể
`404`	Tổ chức chưa có subscription nào đang hoạt động

Request thực tế gửi đi

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: eContract-Webhook/1.0
X-Webhook-Event: webhook.test
X-Webhook-Id: evt_test_770e8400-e29b-41d4-a716-446655440000
X-Webhook-Signature: sha256=854bba9ebf762164a8b3560aeaeb6c6969f7d98c10b613252d6ecd93ecbc4de4

{"createdAt":"2026-05-16T10:00:00.000Z","data":{"message":"This is a test ping from eContract webhook system.","metadata":{},"subscriptionId":"550e8400-e29b-41d4-a716-446655440000","triggeredBy":"super_admin"},"id":"evt_test_770e8400-e29b-41d4-a716-446655440000","type":"webhook.test"}

Body trên dây nén và sắp xếp khoá theo alphabet, khác thứ tự khối JSON minh hoạ ở trên. Luôn HMAC trên raw body nhận được, đừng parse rồi serialize lại.

Tự kiểm thử bằng curl

Không cần chờ quản trị viên bấm Test: tự bắn một request giống hệt vào endpoint của bạn. Copy nguyên khối dưới đây, sửa đúng 2 dòng đầu, dán vào terminal (bash hoặc zsh; macOS và Linux đều chạy).

# ─── SỬA 2 DÒNG NÀY ───────────────────────────────────────────────────────────
WEBHOOK_SECRET='dan_secret_quan_tri_vien_da_cap'
TARGET_URL='https://your-domain.com/webhooks/econtract'   # endpoint webhook CỦA BẠN
# ──────────────────────────────────────────────────────────────────────────────

UUID="$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)"
EVENT_ID="evt_test_$(printf '%s' "$UUID" | tr 'A-Z' 'a-z')"
CREATED_AT="$(date -u +%Y-%m-%dT%H:%M:%S.000Z)"

# Khoá sắp xếp alphabet, không khoảng trắng — đúng chuỗi byte hệ thống gửi và ký
BODY="{\"createdAt\":\"$CREATED_AT\",\"data\":{\"message\":\"This is a test ping from eContract webhook system.\",\"metadata\":{},\"subscriptionId\":\"550e8400-e29b-41d4-a716-446655440000\",\"triggeredBy\":\"super_admin\"},\"id\":\"$EVENT_ID\",\"type\":\"webhook.test\"}"

# Ký trên đúng $BODY, không phải trên bản JSON đã format lại
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -r | cut -d' ' -f1)"

curl -i -s -X POST "$TARGET_URL" \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: eContract-Webhook/1.0' \
  -H 'X-Webhook-Event: webhook.test' \
  -H "X-Webhook-Id: $EVENT_ID" \
  -H "X-Webhook-Signature: $SIG" \
  --max-time 10 \
  --data-raw "$BODY"

Đạt khi dòng đầu output là HTTP/1.1 2xx. TARGET_URL là endpoint của chính bạn, không phải endpoint của econtractid.

Chưa dựng xong endpoint?

# Cửa sổ 1 — nhận request, tự xác thực HMAC, in kết quả. Dừng bằng Ctrl+C
WH_SECRET='dan_secret_quan_tri_vien_da_cap' python3 - <<'PY'
import hmac, hashlib, os
from http.server import BaseHTTPRequestHandler, HTTPServer
SECRET = os.environ['WH_SECRET'].encode()
class H(BaseHTTPRequestHandler):
    def do_POST(self):
        raw = self.rfile.read(int(self.headers.get('Content-Length', 0)))
        expected = 'sha256=' + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
        ok = hmac.compare_digest(self.headers.get('X-Webhook-Signature', ''), expected)
        print(f"event={self.headers.get('X-Webhook-Event')} "
              f"id={self.headers.get('X-Webhook-Id')} chu_ky_hop_le={ok}", flush=True)
        self.send_response(200 if ok else 401); self.end_headers(); self.wfile.write(b'ok')
    def log_message(self, *a): pass
HTTPServer(('127.0.0.1', 8899), H).serve_forever()
PY

# Cửa sổ 2 — dùng URL này cho khối curl ở trên
TARGET_URL='http://127.0.0.1:8899/webhooks/econtract'

TARGET_URL='https://api.econtractid.com/api/webhook-test/thu-nghiem'

Receiver local xác thực chữ ký thật — in chu_ky_hop_le=True là HMAC hai bên khớp. Sandbox /api/webhook-test/{tag} chỉ ghi lại request và luôn trả 201.

Sandbox chỉ dùng khi onboard: không xác thực chữ ký, ghi nguyên headers + body ra đĩa máy chủ. Đừng gửi dữ liệu thật, đừng trỏ subscription production vào đó.

Vector kiểm chứng chữ ký

Kiểm tra hàm HMAC của bạn không cần gọi mạng. Body mẫu ở trên, secret whsec_demo_secret → chữ ký bắt buộc phải ra:

sha256=854bba9ebf762164a8b3560aeaeb6c6969f7d98c10b613252d6ecd93ecbc4de4

printf '%s' '{"createdAt":"2026-05-16T10:00:00.000Z","data":{"message":"This is a test ping from eContract webhook system.","metadata":{},"subscriptionId":"550e8400-e29b-41d4-a716-446655440000","triggeredBy":"super_admin"},"id":"evt_test_770e8400-e29b-41d4-a716-446655440000","type":"webhook.test"}' \
  | openssl dgst -sha256 -hmac 'whsec_demo_secret' -r

Ra khác nghĩa là code của bạn thêm/bớt byte — thường do trailing newline hoặc đã parse rồi serialize lại body.

Cách phản hồi

Vẫn xác thực HMAC như event thật, rồi trả 200 mà không chạy nghiệp vụ.

Đọc kết quả

Kết quả	Nguyên nhân thường gặp
`httpStatus: 0`	Sai domain, DNS chưa trỏ, firewall chặn, TLS không hợp lệ, hoặc quá 10 giây
`301` / `302`	URL đăng ký đang redirect — hệ thống không đi theo, đăng ký thẳng URL đích
`401` / `403`	Endpoint có xác thực riêng, hoặc chữ ký lệch do sai secret / parse lại body trước khi HMAC
`404` / `405`	Sai đường dẫn, hoặc route không nhận `POST`
`2xx` mà latency ~10 000 ms	Đang xử lý đồng bộ trong request — trả `2xx` trước, xử lý nền sau

Uỷ quyền gửi email

Áp dụng cho 4 event có email tương ứng: task_assigned_internal, task_assigned_external, task_rejected, process_finished. notification.task_completed không có email nào của econtractid đi kèm nên không thuộc cơ chế này. Mặc định econtractid gửi email cho tất cả người nhận. Khi bật uỷ quyền, econtractid ngừng gửi email cho người nhận bên ngoài — nhưng chỉ khi thoả cả hai điều kiện:

Event nằm trong danh sách uỷ quyền của tổ chức (quản trị viên cấu hình)
Tổ chức có ít nhất một webhook subscription đang hoạt động lắng nghe event đó

Chỉ người nhận bên ngoài bị ngừng gửi; nhân sự nội bộ vẫn nhận email từ econtractid. Webhook hết retry mà chưa 2xx thì không có email bù — theo dõi nhật ký gửi trên giao diện quản trị.

Xác thực chữ ký

// Webhook secret được cấp khi onboarding
mac := hmac.New(sha256.New, []byte(webhookSecret))
mac.Write(rawBody)
expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(expected), []byte(headerSig)) {
  http.Error(w, "invalid signature", 401)
  return
}

// Chống xử lý trùng — dùng X-Webhook-Id
webhookId := r.Header.Get("X-Webhook-Id")
if exists := checkProcessed(webhookId); exists {
  w.WriteHeader(200) // đã xử lý rồi, vẫn ack
  return
}
markProcessed(webhookId)

// Chống phát lại — createdAt nằm trong body nên đã được ký
envelope := unmarshalJSON(rawBody)
createdAt, _ := time.Parse(time.RFC3339, envelope.CreatedAt)
if time.Since(createdAt) > 5*time.Minute {
  http.Error(w, "payload too old", 401)
  return
}

Retry

Nếu hệ thống của bạn trả về mã khác 2xx hoặc timeout (10 giây), hệ thống sẽ gửi lại:

Lần	Chờ	Tổng thời gian
1	ngay lập tức	0s
2	1 giây	1s
3	10 giây	11s
4	1 phút	71s
5	10 phút	11 phút
6 (cuối)	1 giờ	~71 phút

Sau lần thứ 6 thất bại, event được đánh dấu EXHAUSTED. Bạn khôi phục bằng cách gọi GET /integration/documents/{documentId}.

Khuyến nghị triển khai

Việc	Lý do
Trả `2xx` ngay, xử lý bất đồng bộ	Timeout là 10 giây
Lưu `X-Webhook-Id` để bỏ qua bản trùng	Retry gửi lại cùng ID
Xác thực chữ ký trước khi parse body	Chặn payload giả mạo
Kiểm tra `createdAt` không quá 5 phút	Chống tấn công phát lại
Dùng HTTPS với chứng chỉ hợp lệ	Bắt buộc
Cảnh báo khi không nhận webhook quá 1 giờ	Dự phòng bằng endpoint tra cứu

Tổng quan

Xác thực

Endpoints

Mã lỗi

Webhook

Luồng gửi

Headers

Event và payload

Danh mục event

Payload tham chiếu

Payload — `webhook.test`

Khác biệt so với event thật

Tự bắn ping qua API

Request thực tế gửi đi

Tự kiểm thử bằng curl

Chưa dựng xong endpoint?

Vector kiểm chứng chữ ký

Cách phản hồi

Đọc kết quả

Uỷ quyền gửi email

Xác thực chữ ký

Retry

Khuyến nghị triển khai

​Luồng gửi

​Headers

​Event và payload

Danh mục event

Payload tham chiếu

​Payload — webhook.test

​Khác biệt so với event thật

​Tự bắn ping qua API

​Request thực tế gửi đi

​Tự kiểm thử bằng curl

​Chưa dựng xong endpoint?

​Vector kiểm chứng chữ ký

​Cách phản hồi

​Đọc kết quả

​Uỷ quyền gửi email

​Xác thực chữ ký

​Retry

​Khuyến nghị triển khai

Luồng gửi

Headers

Event và payload

Payload — `webhook.test`

Khác biệt so với event thật

Tự bắn ping qua API

Request thực tế gửi đi

Tự kiểm thử bằng curl

Chưa dựng xong endpoint?

Vector kiểm chứng chữ ký

Cách phản hồi

Đọc kết quả

Uỷ quyền gửi email

Xác thực chữ ký

Retry

Khuyến nghị triển khai