Thêm cấu hình Webhook mới

Webhook code là gì?

code là khóa định danh dùng để truy xuất cấu hình webhook từ bảng tenant_webhook. Khi cần gửi webhook, service dùng code để tìm bản ghi tương ứng và lấy thông tin: endpoint, auth config, timeout, retry policy.

// Tìm webhook config bằng code
tenantWebhookRepository.findByTenantIdAndCodeAndStatus(tenantId, "NEBULA_SIGNAL_UPDATE", TenantWebhookStatus.ACTIVE);

Code hiện có

Code	Chức năng
NEBULA_SIGNAL_UPDATE	Gửi thông báo tín hiệu giao dịch Nebula (ticker, type, volume, date)

Ví dụ code có thể thêm

Code	Chức năng
ORDER_STATUS_UPDATE	Gửi thông báo khi trạng thái lệnh thay đổi
PORTFOLIO_CHANGE	Gửi thông báo khi danh mục thay đổi
PRICE_ALERT	Gửi thông báo cảnh báo giá

---

Các trường của TenantWebhook

Bảng: tenant_webhook

Trường	Kiểu	Bắt buộc	Mô tả
id	Long (auto)	-	ID tự tăng
tenant_id	Long	Có	ID của tenant
code	String	Có	Khóa định danh chức năng webhook. Ví dụ: NEBULA_SIGNAL_UPDATE
name	String	Không	Tên mô tả để quản lý. Ví dụ: "Nebula Signal Webhook"
endpoint	Text	Có	URL endpoint của tenant nhận webhook. Ví dụ: https://api.partner.com/webhook
timeout	Integer	Không	Timeout (ms). Mặc định: 30000 (30s)
retry_policy	Integer	Không	1 = EXPONENTIAL_BACKOFF (60s, 120s, …), 2 = IMMEDIATE (10s). Mặc định: 1
status	Integer	Có	1 = ACTIVE, 2 = INACTIVE, 3 = SUSPENDED
tenant_auth_config_ids	Text (JSON)	Không	Danh sách ID auth config. Ví dụ: [1, 2]

Ràng buộc duy nhất: (tenant_id, code) — mỗi tenant chỉ có một config cho mỗi code.

---

Các trường của TenantAuthConfig

Bảng: tenant_auth_config

Trường	Kiểu	Bắt buộc	Mô tả
id	Long (auto)	-	ID tự tăng
tenant_id	Long	Có	ID của tenant
name	String	Không	Tên mô tả. Ví dụ: "API Key cho partner X"
auth_type	Integer	Có	1 = API_KEY, 2 = BASIC, 3 = HMAC
auth_value	String (encrypted)	Có	Giá trị xác thực (được mã hóa trong DB)
auth_location	Text (JSON)	Có	Cấu hình vị trí và cách áp dụng auth

Chi tiết auth_value theo loại auth

Loại	Giá trị auth_value
API_KEY	Chuỗi API key. Ví dụ: "sk-abc123xyz"
BASIC	username:password. Ví dụ: "admin:secret123"
HMAC	Secret key. Ví dụ: "hmac-secret-key-abc123"

Chi tiết auth_location theo loại auth

API_KEY

Gửi API key trong header:

{
  "to": "header",
  "key": "X-API-KEY"
}

Gửi API key trong query parameter:

{
  "to": "query",
  "key": "apiKey"
}

Trường	Mô tả
to	Vị trí: "header" hoặc "query"
key	Tên header hoặc tên query param

BASIC

{
  "to": "header",
  "key": "Authorization"
}

Hệ thống tự động Base64 encode auth_value và gửi: Authorization: Basic {base64}

HMAC

Gửi chữ ký trong header:

{
  "to": "header",
  "key": "X-Signature",
  "algorithm": "SHA256",
  "include": [
    "method",
    "path",
    "query",
    "body"
  ],
  "recvWindow": 5000
}

Gửi chữ ký trong query parameter:

{
  "to": "query",
  "key": "signature",
  "algorithm": "SHA256",
  "include": [
    "method",
    "path",
    "query",
    "body"
  ],
  "recvWindow": 5000
}

Trường	Mô tả	Mặc định
to	Vị trí chữ ký: "header" hoặc "query"	-
key	Tên header hoặc query param chứa chữ ký	-
algorithm	Thuật toán HMAC: "SHA256"	"SHA256"
include	Các thành phần tham gia payload ký	["method", "path", "query", "body"]
recvWindow	Thời gian hiệu lực chữ ký (ms)	5000

Các giá trị include hỗ trợ:

Giá trị	Mô tả
method	HTTP method (luôn là POST)
path / url	URL path (ví dụ: /webhook/receive)
query	Query parameters (sắp xếp theo key, không bao gồm signature)
body	Request body (JSON đã minify)

Khi to = "query", hệ thống tự động thêm timestamp và recvWindow vào query params trước khi tính chữ ký.

---

Các bước thêm webhook mới

Bước 1: Tạo auth config

INSERT INTO tenant_auth_config (tenant_id, name, auth_type, auth_value, auth_location)
VALUES (
    123,                          -- tenant_id
    'API Key cho Partner X',      -- name
    1,                            -- auth_type: 1=API_KEY
    'sk-abc123xyz',               -- auth_value (sẽ được encrypt)
    '{"to":"header","key":"X-API-KEY"}'  -- auth_location
);
-- Giả sử id = 10

Bước 2: Tạo webhook config

INSERT INTO tenant_webhook (tenant_id, code, name, endpoint, timeout, retry_policy, status, tenant_auth_config_ids)
VALUES (
    123,                                    -- tenant_id
    'ORDER_STATUS_UPDATE',                  -- code: khóa định danh
    'Order Status Webhook',                 -- name
    'https://api.partner.com/webhook/order', -- endpoint
    30000,                                  -- timeout (ms)
    1,                                      -- retry_policy: 1=EXPONENTIAL_BACKOFF
    1,                                      -- status: 1=ACTIVE
    '[10]'                                  -- tenant_auth_config_ids: liên kết auth config
);

Bước 3: Sử dụng trong code

Xem Hướng dẫn sử dụng Webhook để lấy config và gọi WebhookService.sendWebhook().

---

Ví dụ cấu hình đầy đủ theo loại auth

Ví dụ 1: API_KEY (header)

-- Auth config
INSERT INTO tenant_auth_config (tenant_id, name, auth_type, auth_value, auth_location)
VALUES (123, 'API Key', 1, 'sk-abc123xyz', '{"to":"header","key":"X-API-KEY"}');

-- Webhook config
INSERT INTO tenant_webhook (tenant_id, code, name, endpoint, timeout, retry_policy, status, tenant_auth_config_ids)
VALUES (123, 'MY_WEBHOOK', 'My Webhook', 'https://api.partner.com/webhook', 30000, 1, 1, '[1]');

Request gửi đi:

POST https://api.partner.com/webhook
Headers:
  Content-Type: application/json
  X-API-KEY: sk-abc123xyz
Body: {...payload...}

Ví dụ 2: BASIC

-- Auth config
INSERT INTO tenant_auth_config (tenant_id, name, auth_type, auth_value, auth_location)
VALUES (123, 'Basic Auth', 2, 'admin:secret123', '{"to":"header","key":"Authorization"}');

-- Webhook config
INSERT INTO tenant_webhook (tenant_id, code, name, endpoint, timeout, retry_policy, status, tenant_auth_config_ids)
VALUES (123, 'MY_WEBHOOK', 'My Webhook', 'https://api.partner.com/webhook', 30000, 1, 1, '[1]');

Request gửi đi:

POST https://api.partner.com/webhook
Headers:
  Content-Type: application/json
  Authorization: Basic YWRtaW46c2VjcmV0MTIz
Body: {...payload...}

Ví dụ 3: HMAC (header)

-- Auth config
INSERT INTO tenant_auth_config (tenant_id, name, auth_type, auth_value, auth_location)
VALUES (123, 'HMAC Auth', 3, 'hmac-secret-key-abc123',
    '{"to":"header","key":"X-Signature","algorithm":"SHA256","include":["method","path","body"],"recvWindow":5000}');

-- Webhook config
INSERT INTO tenant_webhook (tenant_id, code, name, endpoint, timeout, retry_policy, status, tenant_auth_config_ids)
VALUES (123, 'MY_WEBHOOK', 'My Webhook', 'https://api.partner.com/webhook', 30000, 1, 1, '[1]');

Request gửi đi:

POST https://api.partner.com/webhook
Headers:
  Content-Type: application/json
  X-Signature: a1b2c3d4e5f6... (HMAC-SHA256 signature)
Body: {...payload...}

Ví dụ 4: HMAC (query)

-- Auth config
INSERT INTO tenant_auth_config (tenant_id, name, auth_type, auth_value, auth_location)
VALUES (123, 'HMAC Query Auth', 3, 'hmac-secret-key-abc123',
    '{"to":"query","key":"signature","algorithm":"SHA256","include":["method","path","query","body"],"recvWindow":5000}');

-- Webhook config
INSERT INTO tenant_webhook (tenant_id, code, name, endpoint, timeout, retry_policy, status, tenant_auth_config_ids)
VALUES (123, 'MY_WEBHOOK', 'My Webhook', 'https://api.partner.com/webhook', 30000, 1, 1, '[1]');

Request gửi đi:

POST https://api.partner.com/webhook?recvWindow=5000&signature=a1b2c3...&timestamp=1711612800000
Headers:
  Content-Type: application/json
Body: {...payload...}

Ví dụ 5: Nhiều auth config

-- API Key auth
INSERT INTO tenant_auth_config (tenant_id, name, auth_type, auth_value, auth_location)
VALUES (123, 'API Key', 1, 'sk-abc123', '{"to":"header","key":"X-API-KEY"}');
-- Giả sử id = 10

-- HMAC auth
INSERT INTO tenant_auth_config (tenant_id, name, auth_type, auth_value, auth_location)
VALUES (123, 'HMAC Signature', 3, 'secret-key',
    '{"to":"header","key":"X-Signature","algorithm":"SHA256","include":["method","path","body"]}');
-- Giả sử id = 11

-- Webhook config với 2 auth config
INSERT INTO tenant_webhook (tenant_id, code, name, endpoint, timeout, retry_policy, status, tenant_auth_config_ids)
VALUES (123, 'MY_WEBHOOK', 'My Webhook', 'https://api.partner.com/webhook', 30000, 1, 1, '[10, 11]');

Request gửi đi:

POST https://api.partner.com/webhook
Headers:
  Content-Type: application/json
  X-API-KEY: sk-abc123
  X-Signature: a1b2c3d4e5f6...
Body: {...payload...}