LINE Webhook nhiều sự kiện: xử lý lỗi một phần trong lô
Một yêu cầu webhook của LINE Messaging API có thể chứa nhiều sự kiện, kể cả từ những người dùng khác nhau. Đừng chỉ xử lý events[0], gán toàn bộ yêu cầu cho người gửi đầu tiên hoặc trả về thành công khi mới lưu được một phần. Hãy xác minh chữ ký, lưu bền vững tất cả sự kiện rồi mới trả 200. Khử trùng theo webhookEventId của từng sự kiện để lần gửi lại không lặp lại thao tác nghiệp vụ.
Những điểm chính
- Một HTTP request không nhất thiết tương ứng với một sự kiện, người dùng hay cuộc hội thoại.
- Phản hồi xác nhận áp dụng cho cả yêu cầu; bản ghi lưu trữ và trạng thái xử lý cần tách theo sự kiện.
deliveryContext.isRedeliverylà thông tin chẩn đoán, không phải khóa khử trùng.- Cơ chế gửi lại của LINE không thay thế kho lưu trữ bền vững hay việc thử lại tác vụ của ứng dụng.
Vì sao chỉ xử lý sự kiện đầu tiên sẽ bỏ sót công việc
Hướng dẫn phát triển của LINE nêu rõ rằng sự kiện tin nhắn của người A và sự kiện theo dõi của người B có thể nằm trong cùng một webhook. Tài liệu Messaging API định nghĩa mảng events cùng các đối tượng bên trong.
| Ranh giới | Ý nghĩa | Cách làm sai |
|---|---|---|
| HTTP request | Lần chuyển giao cần xác thực và xác nhận | Coi sự kiện đầu tiên thành công là cả yêu cầu thành công |
| Đối tượng sự kiện | Sự kiện có loại, nguồn và ID riêng | Dùng người gửi hoặc trường tin nhắn đầu tiên cho các sự kiện còn lại |
Định tuyến theo type và source của chính từng sự kiện. Sự kiện theo dõi không phải tin nhắn bị thiếu nội dung. destination ở cấp cao nhất xác định bot nhận, không phải khách hàng chung của mọi sự kiện trong lô.
Mảng rỗng là một trường hợp kiểm tra kết nối hợp lệ riêng. Xem hướng dẫn xử lý events rỗng cho luồng đó. Bài này tập trung vào lô có dữ liệu nhưng việc tiếp nhận thất bại giữa chừng.
Chỉ xác nhận sau khi đã lưu toàn bộ lô
Trước tiên, làm theo hướng dẫn xác minh chữ ký LINE: dùng channel secret để kiểm tra x-line-signature trên nội dung yêu cầu nguyên vẹn, rồi mới phân tích JSON. Gắn yêu cầu với cấu hình kênh thực sự dùng để xác minh, không chọn khách hàng hay tenant từ sự kiện đầu tiên.
Thiết kế được đề xuất là một bảng tiếp nhận sự kiện trong cơ sở dữ liệu:
- Kiểm tra cấu trúc ngoài và các định danh cần thiết của mọi sự kiện.
- Trong một transaction, chèn từng sự kiện với khóa duy nhất kết hợp định danh kênh của ứng dụng và
webhookEventId. - Khóa đã tồn tại nghĩa là sự kiện đã được tiếp nhận. Không đặt lại trạng thái xử lý cũ thành chờ xử lý.
- Commit trước khi trả
200. Worker đọc các hàng đã commit và thực hiện tác vụ chậm riêng.
Đoạn JavaScript sau chỉ minh họa ranh giới này. inbox.transaction và tx.insertIfAbsent là lớp trừu tượng do ứng dụng triển khai, không phải phương thức LINE hay SDK. Cần có transaction thực và ràng buộc duy nhất. channelKey lấy từ cấu hình bộ nhận đáng tin cậy; dữ liệu đầu vào đã được xác minh chữ ký.
async function acceptVerifiedLineBatch(payload, channelKey, inbox) {
if (!payload || !Array.isArray(payload.events)) {
throw new Error('Invalid events array');
}
for (const event of payload.events) {
if (!event || typeof event.webhookEventId !== 'string' ||
event.webhookEventId.length === 0 ||
typeof event.type !== 'string') {
throw new Error('Invalid event envelope');
}
}
await inbox.transaction(async (tx) => {
for (const event of payload.events) {
await tx.insertIfAbsent(channelKey, event.webhookEventId, event);
}
});
return 200;
}
Đây không phải HTTP server hoàn chỉnh. Mã gọi phải từ chối chữ ký không hợp lệ, xử lý lỗi phân tích dữ liệu và không trả thành công nếu kiểm tra hoặc commit thất bại. Khi bộ lưu trữ tạm thời gặp lỗi, có thể chọn phản hồi ngoài 2xx như 503. Đây là chính sách ứng dụng, không phải cam kết rằng LINE sẽ khôi phục mọi sự kiện.
Không nên ghi bảng tiếp nhận rồi gửi vào hàng đợi bằng hai thao tác độc lập mà thiếu cơ chế phục hồi. Nếu tiến trình dừng giữa hai lần ghi, công việc đã xác nhận có thể không được worker phát hiện. Cho worker đọc trực tiếp bảng bền vững, hoặc dùng transactional outbox để chuyển tác vụ.
Khôi phục lỗi một phần mà không phụ thuộc danh tính cả lô
Hướng dẫn nhận tin nhắn của LINE cho biết sự kiện có thể trùng và khuyến nghị dùng webhookEventId để phát hiện. Khi gửi lại, ID sự kiện được giữ nguyên còn deliveryContext.isRedelivery thay đổi. Đừng giả định cùng nhóm sự kiện sẽ lại đến cùng nhau, cũng đừng dùng hash của toàn bộ HTTP body làm khóa khử trùng nghiệp vụ.
Với lô giả định gồm sự kiện A và B:
| Điểm xảy ra lỗi | Kết quả nên có |
|---|---|
| Transaction thất bại khi lưu B | Rollback các bản ghi mới; không xác nhận tiếp nhận thành công |
| A đã được lưu từ yêu cầu trước | Giữ bản ghi A và vẫn tiếp nhận B |
| Commit thành công nhưng HTTP response bị mất | ID lặp lại tìm được hàng cũ, không tạo tác vụ mới |
| Worker lỗi sau phản hồi HTTP thành công | Thử lại từ bảng của ứng dụng, không chờ LINE gửi lại |
| Loại sự kiện hợp lệ nhưng chưa có bộ xử lý | Lưu để xem xét có kiểm soát; không âm thầm bỏ các sự kiện bên cạnh |
Nếu hệ thống hiện tại commit từng sự kiện riêng, giữ những bản ghi đã lưu và khử trùng khi nhận lại. Lần insert đầu thành công không có nghĩa cả yêu cầu đã hoàn tất.
Việc thử lại của worker cần biện pháp riêng. Cập nhật CRM hoặc gửi trả lời có thể đã thành công trước khi worker ghi nhận hoàn tất rồi gặp sự cố. Giữ nguyên trạng thái chưa rõ kết quả và dùng cơ chế idempotency được tài liệu hệ thống đích hỗ trợ nếu có. Với phản hồi tin nhắn, hướng dẫn khôi phục reply token giải thích vì sao sự kiện lặp lại không tạo ra một cơ hội gửi trả lời độc lập mới.
Tách giới hạn gửi lại của LINE khỏi hợp đồng UnifyPort
LINE chỉ gửi lại khi tính năng này được bật và phản hồi webhook thất bại. LINE không công bố số lần hoặc khoảng thời gian thử lại, đồng thời không bảo đảm cơ chế này luôn chuyển giao thành công. Thứ tự nhận cũng có thể khác thứ tự phát sinh. Giữ timestamp làm ngữ cảnh; vị trí trong lô không phải thứ tự toàn cục.
Giao diện không chính thức của UnifyPort là đường kết nối riêng cho tài khoản nhắn tin đã kết nối. Cấu trúc sự kiện chuẩn dùng id, type, provider, account_id, occurred_at và data, không phải mảng events gốc của LINE. Hợp đồng chuyển giao dùng X-Device-Signature khi cấu hình signing_secret, và mọi phản hồi 2xx đều xác nhận lần chuyển giao.
Có thể dùng chung thiết kế lưu trữ bền vững, nhưng không dùng chung parser hay chuỗi tạo chữ ký. Thiếu events không có nghĩa đó là yêu cầu xác minh với mảng rỗng. Nếu cần danh tính LINE Official Account, hãy giữ đường Messaging API chính thức; đổi tích hợp không phải cách khôi phục một yêu cầu đã được nhận một phần.
Câu hỏi thường gặp
Một sự kiện thất bại thì vẫn trả thành công được không?
Chỉ khi tất cả sự kiện đã được lưu bền vững, còn lỗi nằm ở bước xử lý sau mà hệ thống của bạn tự khôi phục được. Nếu có sự kiện chưa lưu, không nên xác nhận tiếp nhận thành công cả yêu cầu.
Có nên bỏ mọi sự kiện có isRedelivery không?
Không. Đó có thể là bản sao đầu tiên bạn nhận thành công. Hãy tra bản ghi khử trùng bền vững thay vì bỏ trực tiếp.
Promise.all có làm lô an toàn không?
Không. Các thao tác đồng thời vẫn có thể chỉ thành công một phần. Sự an toàn đến từ lưu trữ bền vững, khóa duy nhất và cơ chế khôi phục, không phải cách lập lịch của JavaScript.
Bước tiếp theo và nguồn tham khảo
Hãy kiểm thử lô có nhiều người dùng, sự kiện cũ xen sự kiện mới, commit thất bại, mất phản hồi xác nhận và worker dừng giữa chừng. Đây là các bài kiểm thử đề xuất, không phải kết quả đã chạy. Với bộ nhận UnifyPort riêng, bắt đầu từ tài liệu chuyển giao webhook.
Nguồn chính thức được đối chiếu ngày 2026-11-13:
Biến tích hợp nhắn tin thành một pipeline sản phẩm ổn định.
Bắt đầu bằng cách gửi qua một API, rồi đưa mọi tin nhắn inbound trở lại hệ thống kinh doanh bằng sự kiện chuẩn.