ADR-0004. Bảng WebhookConfig thay vì cấu hình routing tĩnh

Trường	Giá trị
Trạng thái	Accepted
Ngày	2026-03-08
Người quyết định	payment-team
Thay thế	—

Bối cảnh

• Payment phát webhook khi trạng thái transaction/attempt thay đổi. Subscriber (sale, finance, tích hợp tùy chỉnh) cần endpoint của họ nhận các sự kiện này.
• Hai cách cấu hình routing:
  1. Cấu hình tĩnh (env vars / yaml) — endpoint nhúng cứng vào deployment.
  2. Registry động — các row WebhookConfig lưu trong DB; admin có thể đăng ký subscriber mới tại runtime.

Quyết định

Sử dụng bảng WebhookConfig với endpoint CRUD (POST /webhook-configs). Mỗi row có url, eventTypes[], status, tùy chọn signingMethod + secret, và metadata per-row (timeout, max retries).

WebhookEventHandlerHelper.handle() truy vấn các config đang hoạt động được lọc theo loại sự kiện, dispatch tới từng cái.

Hệ quả

Ưu điểm	Nhược điểm
Subscriber mới được thêm mà không cần redeploy	Config drift giữa các môi trường (DB-managed)
Retry/timeout/HMAC theo từng subscriber	Cần authorization để quản lý webhook config (bảo mật)
Bật/tắt subscriber qua status	Truy vấn DB trên mỗi sự kiện — cần index (status, eventTypes GIN) để tối ưu hiệu năng
Audit trail qua lịch sử Configuration (nếu được triển khai)	Endpoint test có thể rò rỉ ở prod nếu không được dọn dẹp

Quyết định về schema

• eventTypes: text[] (mảng Postgres) — hỗ trợ filter qua eventTypes @> ARRAY[event].
• metadata: jsonb với mặc định { timeoutMs: 30000, maxRetries: 3 } — có thể tinh chỉnh per-row.
• Soft-delete được hỗ trợ (deactivate qua status được ưu tiên cho audit).

Phương án thay thế đã cân nhắc

Lựa chọn	Ưu điểm	Nhược điểm	Lý do từ chối
URL hardcode trong env	Đơn giản	Không thay đổi runtime; không scale với nhiều subscriber	Không linh hoạt
Routing service mesh (ví dụ Istio)	Tách ứng dụng khỏi URL	Hạ tầng nặng	Quá mức cần thiết
Pub/sub bên ngoài (Kafka topic)	Tách rời; subscriber tiêu thụ	Bất đối xứng — sale đã dùng pattern HTTP webhook	Chi phí migration không xứng đáng

Tham chiếu

• core/src/models/schemas/public/webhook-config/schema.ts
• controllers/webhook-config/controller.ts
• helpers/webhook-event-handler/helper.ts