Đă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.
EndpointPOST
https://api.lrsvn.com/v1/webhooksTạ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 -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ểu | Mô tả |
|---|---|---|
| url | string | URL 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. |
| events | string[] | 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/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ện | Phát khi | Trường trong data |
|---|---|---|
| order.paid | Đơn hàng thanh toán thành công. | order_id, amount, currency |
| invoice.paid | Hoá đơn được thanh toán. | invoice_id |
| service.operation.completed | Thao tác trên dịch vụ (ví dụ VPS) hoàn tất. | service_id, operation_id, action |
| ticket.created | Có yêu cầu hỗ trợ mới. | id, code, status |
| ticket.customer_replied | Khách trả lời yêu cầu hỗ trợ. | id, code, status |
| ticket.staff_replied | Nhân viên trả lời yêu cầu hỗ trợ. | id, code, status |
| ticket.status_changed | Trạng thái yêu cầu hỗ trợ đổi. | id, code, status |
| link.run.completed | Mộ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èmsecret).PUT /webhooks/{id}— cập nhật; gửi đủurl,eventsvàenabled.POST /webhooks/{id}/rotate— cấpsecretmớ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
| HTTP | Mã | Khi nào |
|---|---|---|
| 400 | invalid_request | URL không hợp lệ hoặc không phải địa chỉ công khai; sự kiện sai hoặc trùng. |
| 403 | forbidden | Phiên đăng nhập không phải Owner hoặc Admin. |
| 403 | scope_denied | API key không có scope organization:write. |
| 404 | not_found | Không tìm thấy webhook. |