Thử lại khi lỗi
LRS coi lần gửi là thành công khi endpoint trả mã 2xx. Các trường hợp khác được thử lại, tối đa 5 lần, rồi đánh dấu thất bại. Nhật ký gửi lưu 7 ngày.
EndpointGET
https://api.lrsvn.com/v1/webhooks/{id}/deliveriesWebhook là cách gửi "ít nhất một lần": cùng một sự kiện có thể đến nhiều lần nếu phản hồi của bạn bị mất. Hãy xử lý theo id của sự kiện để không làm trùng.
Quy tắc gửi
- Thành công là mã HTTP 2xx. Thân phản hồi bị bỏ qua (chỉ đọc tối đa 64 KB).
- Mỗi lần gửi chờ tối đa 15 giây. LRS không đi theo chuyển hướng, nên 3xx tính là lỗi.
- Khác 2xx, lỗi kết nối hoặc hết thời gian chờ thì thử lại. Mỗi sự kiện được gửi tối đa 5 lần, sau đó chuyển sang
failed. - Webhook bị tắt hoặc bị xoá: các lần gửi còn chờ chuyển sang
failed.
| Kết quả của một lần gửi | Xử lý |
|---|---|
| 2xx | Thành công — delivered. |
| 3xx | Không theo chuyển hướng; tính là lỗi, thử lại. |
| 4xx, 5xx | Lỗi, thử lại. |
| Timeout, lỗi mạng hoặc TLS | Quá 15 giây hoặc không kết nối được: lỗi, thử lại. |
Yêu cầu
curl https://api.lrsvn.com/v1/webhooks/$WEBHOOK_ID/deliveries \
-H "Authorization: Bearer $LRS_API_KEY"Trả về nhật ký 7 ngày gần nhất, mới nhất trước. Hỗ trợ ?page= và ?limit=.
Phản hồi
{
"data": [
{
"id": "whd_7b1e0c93a4d2f8e65c1a0b9d3e7f2a48",
"event": "order.paid",
"status": "delivered",
"attempts": 1,
"response_status": 204,
"created_at": "2026-09-30T10:05:31Z",
"delivered_at": "2026-09-30T10:05:32Z"
}
],
"meta": { "total": 1, "page": 1, "limit": 20 }
}Trường phản hồi
| Trường | Kiểu | Mô tả |
|---|---|---|
| status | string | pending (đang chờ gửi hoặc chờ thử lại), delivered hoặc failed. |
| attempts | integer | Số lần đã gửi, từ 0 đến 5. |
| response_status | integer | Mã HTTP endpoint trả về ở lần gần nhất; null nếu chưa có. |
| delivered_at | string | Thời điểm gửi thành công; null nếu chưa thành công. |
Xử lý phía bạn
- Xác minh chữ ký trước khi đọc nội dung.
- Lưu
idcủa sự kiện và trả2xxngay; việc nặng chuyển sang hàng đợi nội bộ. - Nếu đã thấy
idnày, trả2xxmà không xử lý lại.
Mã lỗi
| HTTP | Mã | Khi nào |
|---|---|---|
| 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. |