Bỏ qua để đến nội dung
  • troubleshooting
  • webhook issues

Xử lý sự cố Webhook & Bị trễ tin nhắn (Webhook Issues)

Webhook là cầu nối thời gian thực (Real-time Callback) giúp nhận tin nhắn ngay lập tức từ Facebook, Zalo, Telegram, SePay hay Zapier về TrolyPage. Nếu Webhook gặp sự cố, tin nhắn từ khách hàng sẽ bị chậm hoặc không xuất hiện trên Hộp thư.

Dấu hiệu nhận biết sự cố Webhook

Phần tiêu đề “Dấu hiệu nhận biết sự cố Webhook”
  • Khách nhắn tin trên Fanpage hoặc Zalo nhưng 10-30 giây sau mới thấy tin nhắn xuất hiện trên TrolyPage (hoặc không thấy xuất hiện).
  • Đơn hàng chuyển khoản thành công nhưng SePay không tự động đổi trạng thái đơn sang Đã chốt.
  • Trang Cài đặt Kênh hiển thị cảnh báo webhook_not_subscribed.

4 Nguyên nhân chính & Hướng khắc phục

Phần tiêu đề “4 Nguyên nhân chính & Hướng khắc phục”

1. Facebook Meta Webhook quá hạn 5 giây (Timeout > 5s)

Phần tiêu đề “1. Facebook Meta Webhook quá hạn 5 giây (Timeout > 5s)”
  • Quy định Meta: Facebook Graph API yêu cầu máy chủ TrolyPage phải phản hồi mã HTTP 200 OK trong vòng 5 giây kể từ khi sự kiện xảy ra. Nếu quá 5s, Meta sẽ đánh giá Webhook bị treo và tạm ngừng gửi sự kiện tiếp theo.
  • Khắc phục: TrolyPage đã áp dụng kiến trúc hàng đợi bất đồng bộ (Async Queue). Nếu vẫn bị trễ, hãy kiểm tra kết nối mạng hoặc liên hệ kỹ thuật qua Support Ticket.

2. Nhả đăng ký Subscribed Fields trên Fanpage

Phần tiêu đề “2. Nhả đăng ký Subscribed Fields trên Fanpage”
  • Thỉnh thoảng Facebook tự động gỡ bỏ sự kiện pages_messaging khỏi Fanpage.
  • Khắc phục:
    1. Mở trang Kênh giao tiếp (/app/channels).
    2. Tìm Fanpage bị sự cố → Bấm Đăng ký lại Webhook.

3. Sai Webhook Secret Key / IP Whitelist (Cổng Thanh toán SePay)

Phần tiêu đề “3. Sai Webhook Secret Key / IP Whitelist (Cổng Thanh toán SePay)”
  • Khi kết nối SePay để nhận đối soát chuyển khoản tự động:
    • Sai đường dẫn Webhook URL hoặc sai API Key / Secret Key.
    • Firewall của ngân hàng chặn truy cập.
  • Khắc phục: Mở Kênh Thanh toán SePay → Copy lại chuẩn xác đường dẫn Webhook URL dán vào cấu hình trên SePay Dashboard.

4. Lỗi Verify Token khi cài đặt ban đầu

Phần tiêu đề “4. Lỗi Verify Token khi cài đặt ban đầu”
  • Khi khai báo Webhook lần đầu trên Facebook Developer Portal hoặc Zalo Developer:
    • Token xác minh (Verify Token) dán ở Developer Portal không khớp với mã trên TrolyPage.
  • Khắc phục: Copy chính xác mã Verify Token được cấp sẵn trong trang Kênh dán vào ô xác minh.

Kiểm tra Nhật ký Webhook (Webhook Debugging Checklist)

Phần tiêu đề “Kiểm tra Nhật ký Webhook (Webhook Debugging Checklist)”
flowchart TD
  MSG[Khách nhắn tin trên Fanpage] --> META[Facebook Webhook Server]
  META -->|Kiểm tra HTTP 200| TROLY[TrolyPage Webhook Receiver]
  TROLY -->|Đưa vào Queue| QUEUE[Async Queue Worker]
  QUEUE -->|Bắn Websocket| CHAT[Hộp thư Realtime ChatArea]

Nếu nghi ngờ Webhook bị ngắt:

  1. Mở cuộc trò chuyện bất kỳ ở Hộp thư → Kiểm tra biểu tượng Wifi góc trên.
  2. Kiểm tra trang Trung tâm Thông báo xem có thông báo mã integration_error hay không.
  3. Nếu vấn đề kéo dài, hãy gửi Support Ticket kèm tên Fanpage và mốc thời gian bị trễ tin nhắn.

Bước tiếp theo

Phần tiêu đề “Bước tiếp theo”