Thông tin tenant cần cung cấp cho webhook mới
Thông tin bắt buộc
1. Webhook endpoint URL
- URL mà hệ thống sẽ gửi HTTP POST request tới
- Phải là HTTPS
- Ví dụ:
https://api.partner.com/webhook/receive
2. Phương thức xác thực
Chọn một trong ba loại (hoặc kết hợp nhiều loại):
Loại 1: API_KEY
| Thông tin | Mô tả | Ví dụ |
|---|---|---|
| API Key | Giá trị API key | sk-abc123xyz |
| Vị trí | Gửi trong header hay query param | header hoặc query |
| Tên header/param | Tên của header hoặc query param | X-API-KEY, apiKey |
Loại 2: BASIC
| Thông tin | Mô tả | Ví dụ |
|---|---|---|
| Username | Tên đăng nhập | admin |
| Password | Mật khẩu | secret123 |
Hệ thống tự động Base64 encode và gửi trong header
Authorization: Basic {base64}
Loại 3: HMAC
| Thông tin | Mô tả | Ví dụ |
|---|---|---|
| Secret Key | Khóa bí mật để ký | hmac-secret-abc123 |
| Algorithm | Thuật toán | SHA256 (mặc định) |
| Vị trí chữ ký | Gửi trong header hay query | header hoặc query |
| Tên header/param | Tên header hoặc query param chứa chữ ký | X-Signature, signature |
| Thành phần cần ký | Các phần tham gia payload ký | method, path, query, body |
| RecvWindow | Thời gian hiệu lực chữ ký (ms) | 5000 (mặc định) |
Thông tin tùy chọn
| Thông tin | Mô tả | Mặc định |
|---|---|---|
| Timeout | Thời gian chờ response (ms) | 30000 (30s) |
| Retry Policy | Chính sách retry khi thất bại | EXPONENTIAL_BACKOFF |
Retry Policy:
- EXPONENTIAL_BACKOFF: Retry sau 60s, 120s, rồi tăng dần. Phù hợp hầu hết trường hợp.
- IMMEDIATE: Retry sau 10s. Phù hợp khi cần gửi lại nhanh.
Yêu cầu kỹ thuật phía tenant
- Trả về HTTP 2xx khi nhận thành công (ví dụ: 200 OK, 201 Created)
- Xử lý idempotent: Có thể nhận cùng một webhook nhiều lần (do retry), cần xử lý trùng lặp
- Response time hợp lý: Nên phản hồi trong vòng 30s (hoặc theo timeout đã cấu hình)
- Nếu dùng HMAC: Cần triển khai logic verify chữ ký phía tenant để đảm bảo webhook đến từ hệ thống
Mẫu thu thập thông tin
Gửi bảng này cho tenant để điền:
+----------------------------+------------------------------+
| Thông tin | Giá trị |
+----------------------------+------------------------------+
| Webhook Code | (VD: ORDER_STATUS_UPDATE) |
| Endpoint URL | https://... |
| Loại xác thực | API_KEY / BASIC / HMAC |
+----------------------------+------------------------------+
| [API_KEY] API Key | |
| [API_KEY] Vị trí | header / query |
| [API_KEY] Tên header/param | |
+----------------------------+------------------------------+
| [BASIC] Username | |
| [BASIC] Password | |
+----------------------------+------------------------------+
| [HMAC] Secret Key | |
| [HMAC] Algorithm | SHA256 (mặc định) |
| [HMAC] Vị trí chữ ký | header / query |
| [HMAC] Tên header/param | |
| [HMAC] Thành phần cần ký | method, path, query, body |
| [HMAC] RecvWindow (ms) | 5000 (mặc định) |
+----------------------------+------------------------------+
| Timeout (ms) | 30000 (mặc định) |
| Retry Policy | EXPONENTIAL_BACKOFF (mặc định)|
+----------------------------+------------------------------+
Ví dụ thông tin tenant cung cấp
Ví dụ 1: Tenant dùng API Key
Endpoint: https://api.partnerx.com/webhook
Xác thực: API_KEY
API Key: pk_live_abc123xyz
Vị trí: header
Tên header: X-API-KEY
Timeout: 15000ms
Retry: EXPONENTIAL_BACKOFF
Ví dụ 2: Tenant dùng HMAC
Endpoint: https://api.partnery.com/v1/webhook/receive
Xác thực: HMAC
Secret Key: sk_hmac_secret_123456
Algorithm: SHA256
Vị trí: header
Tên header: X-Signature
Cần ký: method, path, body
RecvWindow: 10000ms
Timeout: 20000ms
Retry: IMMEDIATE
Ví dụ 3: Tenant dùng Basic Auth
Endpoint: https://webhook.partnerz.com/notify
Xác thực: BASIC
Username: webhook_user
Password: P@ssw0rd!
Timeout: 30000ms
Retry: EXPONENTIAL_BACKOFF