Chuyển tới nội dung chính

Hướng dẫn Admin — Auth Config và Webhook

Tài liệu mô tả thao tác trên Admin Panel để cấu hình TenantAuthConfig và TenantWebhook. Phần nghiệp vụ, bảng dữ liệu và payload: xem Tổng quan hệ thống Webhook và Thêm cấu hình Webhook mới.

Mục lục​

  1. Quyền và điều hướng
  2. Tạo Auth Config
  3. Tạo Webhook Config
  4. Liên kết Auth với Webhook
  5. Ví dụ nhanh
  6. Xử lý sự cố
  7. Ghi chú bảo mật và validation

Quyền và điều hướng​

Quyền cần có

  • TENANT_AUTH_CONFIG — quản lý Auth Config
  • TENANT_WEBHOOK — quản lý Webhook Config

Menu

Mục đíchĐường đi
Auth ConfigModule Core → Tenant Auth Configs
Webhook ConfigModule Core → Tenant Webhooks

Tạo Auth Config​

Luồng chung​

  1. Vào Tenant Auth Configs → Create
  2. Điền Tenant ID, Name (cặp tenantId + name phải duy nhất)
  3. Chọn Auth Type và điền giá trị tương ứng
  4. Cấu hình Auth Location (header hoặc query + tên key)
  5. Save — ghi nhớ ID nếu cần gắn vào webhook

Các loại xác thực (UI)​

Auth TypeÝ nghĩaGiá trị nhập
API Key (1)Gửi khóa APIChuỗi API key
Basic Auth (2)Basic AuthenticationUsername + password (hệ thống mã hóa Base64 khi gửi)
HMAC (3)Chữ ký HMAC-SHA256 trên payloadSecret dùng để ký

Auth Location

  • Header hoặc Query parameter
  • Key name: ví dụ X-API-Key, Authorization, X-Signature (tùy endpoint đối tác)

Gợi ý mặc định thường gặp: API Key → X-API-Key; Basic → Authorization (có prefix Basic ). Chi tiết định dạng auth_location và bảng trường: Thêm cấu hình Webhook mới.

Tạo Webhook Config​

  1. Vào Tenant Webhooks → Create
  2. Tenant ID — bắt buộc
  3. Code — mã định danh chức năng (cặp tenantId + code duy nhất), ví dụ NEBULA_SIGNAL_UPDATE
  4. Name — tên mô tả
  5. Endpoint — URL HTTPS nhận POST, bắt đầu bằng https://
  6. Timeout (ms) — mặc định thường là 30000; phải > 0
  7. Retry policy — Exponential Backoff (khuyến nghị) hoặc Immediate
  8. Status — ACTIVE / INACTIVE / SUSPENDED
  9. Tenant Auth Config IDs (tùy chọn) — chọn từ dropdown hoặc nhập danh sách ID cách nhau bởi dấu phẩy, ví dụ 1, 2, 3

Lưu ý: Nếu endpoint đối tác không cần xác thực, không bắt buộc tạo Auth Config — cứ bỏ trống trường Tenant Auth Config IDs (không chọn, không nhập ID). Hệ thống vẫn gửi webhook bình thường, không gắn header/query auth.

Liên kết Auth với Webhook​

  • Có thể gắn nhiều Auth Config cho một webhook; thứ tự trong danh sách là thứ tự áp dụng.
  • Nếu hai config cùng đặt vào cùng một header key, bản ghi sau ghi đè bản trước.
  • Query parameters được merge vào URL khi gửi.
  • Không cần auth: để trống Tenant Auth Config IDs — không cần điền placeholder hay giá trị giả.

Ví dụ nhanh​

Một webhook + API Key​

  1. Tenant Auth Configs → Create: Tenant ID 1, Name Nebula API Key, type API Key, key sk_live_..., Location Header, Key X-API-Key → Save → ID ví dụ 5.
  2. Tenant Webhooks → Create: cùng tenant, Code NEBULA_SIGNAL_UPDATE, Endpoint https://api.partner.com/webhook/signals, Timeout 30000, Retry Exponential Backoff, Status ACTIVE, Auth IDs 5 → Save.

Kết quả: request webhook có header X-API-Key: ….

Một webhook + API Key và Basic​

Tạo hai Auth Config (API Key + Basic), sau đó tại webhook nhập Tenant Auth Config IDs dạng 6, 7 đúng thứ tự mong muốn. Hệ thống gửi đủ các header/query đã cấu hình.

Clone Auth Config sang tenant khác​

Trên danh sách Auth Config → Clone → đổi Tenant ID và/hoặc Name (và secret nếu cần) → tránh trùng ràng buộc unique.

Xử lý sự cố​

Triệu chứngHướng xử lý
Tenant ID + Name must be uniqueĐổi Name hoặc xóa bản ghi Auth Config trùng
Tenant ID + Code must be uniqueĐổi Code webhook hoặc xóa config cũ
Endpoint must start with https://Chỉ dùng HTTPS; không dùng http://
Auth Config không có trong dropdownTạo Auth Config trước; hoặc nhập trực tiếp ID vào trường Auth IDs
Webhook không gửi đượcKiểm tra Status = ACTIVE, URL, auth đã gắn; xem Kiểm tra log và Webhook Execution
Giá trị auth bị mask trong listHành vi bảo mật; mở View / Edit (nếu có quyền) để xem đầy đủ
Không xóa được Auth ConfigGỡ Auth Config khỏi mọi Tenant Webhooks (cột Auth Configs) rồi thử lại
Clone lỗiĐảm bảo tenantId/name (Auth) hoặc code (Webhook) mới không trùng bản ghi khác

Ghi chú bảo mật và validation​

  • auth_value được mã hóa khi lưu DB; UI có thể giải mã khi xem form nhưng mask trong danh sách.
  • Auth Config: có authType thì phải có authValue; authLocation phải có key.
  • Webhook: endpoint bắt đầu https://; timeout > 0. Trường auth IDs để trống = gửi không kèm xác thực. Nếu có nhập ID thì từng ID phải tồn tại và hợp lệ.

Hỗ trợ​

  1. Đọc thông báo lỗi trên UI
  2. Xem integration / execution log theo Kiểm tra log và Webhook Execution
  3. Xác nhận quyền TENANT_AUTH_CONFIG và TENANT_WEBHOOK
  4. Liên hệ team vận hành nếu vẫn bị chặn