Bỏ qua đến nội dung

Tài liệu kỹ thuật

Tích hợp LRS trong một buổi chiều.

Đăng ký endpoint

Đăng ký một URL HTTPS để LRS gửi sự kiện (đơn hàng đã thanh toán, thao tác dịch vụ hoàn tất…) ngay khi chúng xảy ra, thay vì phải hỏi lại liên tục.

EndpointPOSThttps://api.lrsvn.com/v1/webhooks

Tạo webhook trong bảng điều khiển (Cài đặt → API → Webhook) hoặc gọi API bằng phiên Owner/Admin, hay API key có scope organization:write.

Yêu cầu

cURL
curl -X POST https://api.lrsvn.com/v1/webhooks \
  -H "Authorization: Bearer $LRS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.vn/lrs/webhook",
    "events": ["order.paid", "invoice.paid"]
  }'

Tham số

Tham sốKiểuMô tả
urlstringURL HTTPS công khai, cổng 443, tối đa 2.048 ký tự; không chứa tên người dùng/mật khẩu hay #. Không nhận localhost, tên miền nội bộ hoặc địa chỉ IP riêng.
eventsstring[]Một hoặc nhiều sự kiện trong bảng bên dưới, không trùng nhau.

Phản hồi

HTTP
HTTP/1.1 201 Created

{
  "id": "whk_3c8e1d7a4f",
  "url": "https://app.example.vn/lrs/webhook",
  "events": ["order.paid", "invoice.paid"],
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

secret dùng để xác minh chữ ký và chỉ hiện một lần. Mất secret thì xoay vòng bằng POST /webhooks/{id}/rotate.

Sự kiện

Sự kiệnPhát khiTrường trong data
order.paidĐơn hàng thanh toán thành công.order_id, amount, currency
invoice.paidHoá đơn được thanh toán.invoice_id
service.operation.completedThao tác trên dịch vụ (ví dụ VPS) hoàn tất.service_id, operation_id, action
ticket.createdCó yêu cầu hỗ trợ mới.id, code, status
ticket.customer_repliedKhách trả lời yêu cầu hỗ trợ.id, code, status
ticket.staff_repliedNhân viên trả lời yêu cầu hỗ trợ.id, code, status
ticket.status_changedTrạng thái yêu cầu hỗ trợ đổi.id, code, status
link.run.completedMột lượt LR Link vừa hoàn thành (chiến dịch có hành động webhook).campaign_id, run_id, external_user, completed_at, license_key, code

Màn hình đăng ký webhook liệt kê đầy đủ các sự kiện có thể chọn. Với sự kiện anti-cheat theo thời gian thực, hãy dùng kênh WebSocket.

Quản lý webhook

  • GET /webhooks — danh sách webhook của tổ chức (không kèm secret).
  • PUT /webhooks/{id} — cập nhật; gửi đủ url, events và enabled.
  • POST /webhooks/{id}/rotate — cấp secret mới, secret cũ hết hiệu lực ngay.
  • DELETE /webhooks/{id} — ngừng gửi; nhật ký 7 ngày vẫn xem được.
  • GET /webhooks/{id}/deliveries — nhật ký gửi 7 ngày gần nhất.

Mã lỗi

HTTPMãKhi nào
400invalid_requestURL không hợp lệ hoặc không phải địa chỉ công khai; sự kiện sai hoặc trùng.
403forbiddenPhiên đăng nhập không phải Owner hoặc Admin.
403scope_deniedAPI key không có scope organization:write.
404not_foundKhông tìm thấy webhook.