Tổng quan hệ thống Webhook

Webhook là gì?

Hệ thống Webhook cho phép gửi HTTP POST request tới endpoint của tenant khi có sự kiện xảy ra trong hệ thống. Tenant cấu hình endpoint và phương thức xác thực; hệ thống tự động gửi và retry khi thất bại.

Luồng tổng quan

Các thành phần chính

1. TenantWebhook (Cấu hình webhook)

Lưu cấu hình webhook của tenant: URL endpoint, mã định danh, timeout, chính sách retry, trạng thái và danh sách cấu hình auth.

• Bảng: tenant_webhook
• Ràng buộc duy nhất: (tenant_id, code)

2. TenantAuthConfig (Cấu hình xác thực)

Lưu thông tin xác thực để gửi webhook: loại auth, giá trị (đã mã hóa) và vị trí áp dụng.

• Bảng: tenant_auth_config
• Hỗ trợ 3 loại: API_KEY, BASIC, HMAC

3. WebhookExecution (Theo dõi thực thi)

Lưu chi tiết mỗi lần gửi webhook: URL, headers, request body, response, mã trạng thái HTTP, số lần retry, lỗi.

• Bảng: webhook_execution

Các loại xác thực

Loại	Mô tả
API_KEY	Gửi API key trong header hoặc query parameter
BASIC	Base64 encode credentials, gửi trong header Authorization: Basic {base64}
HMAC	Tính chữ ký từ payload bằng HMAC-SHA256, gửi trong header hoặc query

Chính sách retry

Policy	Mô tả
EXPONENTIAL_BACKOFF	Retry 1: 60s, Retry 2: 120s, Retry 3+: 60s × (retryCount³)
IMMEDIATE	Retry sau 10s

• Số lần retry tối đa: 3
• Retry Worker chạy mỗi 2 phút, xử lý tối đa 100 execution mỗi lần
• Dùng ShedLock để tránh trùng lặp trong cluster

Vòng đời Webhook Execution

Status	Giá trị	Mô tả
RETRY_FAILED	1	Thất bại, chờ retry
SUCCESS	2	Gửi thành công
FAILED	3	Thất bại vĩnh viễn (hết retry)
RETRYING	4	Đang thực hiện retry

File chính liên quan

File	Đường dẫn	Mô tả
WebhookService	application/core/partner/webhook/WebhookService.java	Interface gửi webhook
WebhookServiceImpl	application/core/partner/webhook/impl/WebhookServiceImpl.java	Logic gửi webhook, áp dụng auth
WebhookExecutionService	application/core/partner/webhook/WebhookExecutionService.java	Interface quản lý execution
WebhookExecutionServiceImpl	application/core/partner/webhook/impl/WebhookExecutionServiceImpl.java	Logic retry, tính backoff
TenantWebhookService	application/core/partner/webhook/TenantWebhookService.java	Tìm cấu hình webhook
TenantWebhook	domain/model/credentials/TenantWebhook.java	Entity cấu hình webhook
TenantAuthConfig	domain/model/credentials/TenantAuthConfig.java	Entity cấu hình auth
WebhookExecution	domain/model/partner/WebhookExecution.java	Entity theo dõi execution
WebhookRetryWorker	interfaces/worker/WebhookRetryWorker.java	Worker retry webhook thất bại
AuthLocationDto	application/core/partner/webhook/dto/AuthLocationDto.java	DTO cấu hình vị trí auth
TenantWebhookAdminController	interfaces/admin/generated/TenantWebhookAdminController.java	Admin API quản lý cấu hình webhook

Tất cả đường dẫn tính từ simplize-core/src/main/java/com/simplize/core/

---

Xem thêm

• Hướng dẫn Admin — Auth Config và Webhook — thao tác trên giao diện quản trị.