So Sánh & Hướng Dẫn: Webhook Logs Documentation

🎯 Tổng Quan

2 Log Files Chính

Hệ thống Facebook Messenger Bot sử dụng 2 log files để monitoring và debugging:

📥 webhook_requests.log

Level: Infrastructure Network

Mục đích: Log RAW data từ Facebook

Nội dung: JSON payload nguyên bản

Vị trí: Đầu webhook (ngay khi nhận)

🔧 webhook_processing_debug.log

Level: Application Logic

Mục đích: Log quá trình xử lý của bot

Nội dung: Chi tiết từng bước logic

Vị trí: Trong quá trình xử lý

📊 So Sánh Chi Tiết

Tiêu Chí	webhook_requests.log	webhook_processing_debug.log
Mục đích chính	Verify webhook connectivity	Debug business logic
Level	Infrastructure / Network	Application / Logic
Nội dung	Raw JSON từ Facebook	Chi tiết từng bước xử lý
Câu hỏi trả lời	"Webhook có nhận data không?"	"Bot xử lý như thế nào?"
Thông tin cung cấp	• Event type (message, delivery, read, postback) • Sender ID, Page ID • Message text, mid • Timestamp từ Facebook • Raw payload	• User ID resolution • Duplicate check result • Keyword matching • Script execution • Database operations • Error messages
Khi nào dùng	• Webhook không hoạt động • Debug connectivity • Verify event types • Check sender/page ID	• Bot không phản hồi • Debug matching logic • Find errors in code • Trace workflow
Code tạo log	Đầu file `fb_webhook.php` (POST request handling)	`processWebhookTextMessageEnhanced()` `getUserIdFromPageId()` `markMessageAsProcessed()`
Format	JSON formatted	Plain text với timestamp
File size	Lớn (nhiều event types)	Vừa (chỉ message events)

📝 Ví Dụ Chi Tiết

Example 1: Text Message từ User

📥 webhook_requests.log

=== MESSAGE RECEIVED ===
Time: 2026-02-10 19:24:09
Input: {...}
Decoded: {
  "object": "page",
  "entry": [{
    "time": 1770726248742,
    "id": "557849694089307",
    "messaging": [{
      "sender": {
        "id": "24502905112710899"
      },
      "recipient": {
        "id": "557849694089307"
      },
      "timestamp": 1770726248087,
      "message": {
        "mid": "m_27Lh0z...",
        "text": "test"
      }
    }]
  }]
}

📌 Thông tin rút ra:

✅ Event type: message
✅ Sender ID: 24502905112710899
✅ Page ID: 557849694089307
✅ Message text: "test"
✅ Webhook đang hoạt động

🔧 webhook_processing_debug.log
=== [2026-02-10 19:24:09] PROCESSING TEXT MESSAGE ===
Sender ID: 24502905112710899
Page ID: 557849694089307
Message: test
Message ID: m_27Lh0z...

CHECK 1: Duplicate message check...
Marked as processed: YES

CHECK 2: Response lock check...
CHECK 3: Rate limiting check...
✅ All checks passed - Processing message

Getting user_id from page_id: 557849694089307
  getUserIdFromPageId: Searching...
  ✅ Found from facebook_pages:
    - user_id: 36
    - page_name: DTD Agency
    - is_active: 1
User ID: 36

Saving to conversations table...
Insert result: SUCCESS
Insert ID: 139

Processing message with priority logic...
Response type: multi_step
✅ Processing completed successfully

                                ✅ Thông tin rút ra:
                                ✅ User ID resolved: 36
✅ Database insert: SUCCESS
✅ Keyword matched
✅ Multi-step script executed
✅ Bot đã phản hồi

                            

Example 2: Delivery Receipt (KHÔNG phải tin nhắn)

📥 webhook_requests.log

=== MESSAGE RECEIVED ===
Time: 2026-02-10 16:46:17
Decoded: {
  "messaging": [{
    "sender": {
      "id": "25284377014546673"
    },
    "recipient": {
      "id": "557849694089307"
    },
    "timestamp": 1770716776465,
    "delivery": {
      "watermark": 1766196754605
    }
  }]
}

                                ⚠️ Chú ý:

                                Event type là delivery, KHÔNG phải message

                                → Đây là delivery receipt, không phải tin nhắn text

🔧 webhook_processing_debug.log

(KHÔNG CÓ LOG)

📌 Giải thích:
Bot KHÔNG xử lý delivery receipts → không có log trong webhook_processing_debug.log

Example 3: Echo Message (Tin nhắn của chính bot)

📥 webhook_requests.log

"messaging": [{
  "sender": {
    "id": "557849694089307"  ← PAGE ID
  },
  "recipient": {
    "id": "24502905112710899"
  },
  "message": {
    "mid": "m_pvr1ll...",
    "is_echo": true,        ← ECHO FLAG
    "text": "test 2"
  }
}]

                                ⚠️ Chú ý:

                                • Sender ID = Page ID → Tin nhắn TỪ bot

                                • is_echo: true → Đây là echo message

🔧 webhook_processing_debug.log

=== [2026-02-10 19:24:18] ===
Sender ID: 557849694089307
Page ID: 557849694089307
Message: test 2

⚠️ SKIPPED: sender_id matches page_id

✅ Filter hoạt động đúng:
Bot nhận ra đây là tin nhắn của chính mình và SKIP xử lý → Tránh vòng lặp vô hạn

Example 4: Lỗi - User ID NULL

📥 webhook_requests.log

"messaging": [{
  "sender": {
    "id": "24502905112710899"
  },
  "recipient": {
    "id": "557849694089307"
  },
  "message": {
    "text": "hello bot 123"
  }
}]

✅ Webhook nhận data OK
Có message text, sender ID, page ID hợp lệ

🔧 webhook_processing_debug.log

=== [2026-02-10 19:04:29] ===
Message: hello bot 123

Getting user_id from page_id: 557849694089307
User ID: NULL              ← ❌ VẤN ĐỀ

Saving to conversations table...
❌ EXCEPTION: Column 'user_id' cannot be null
Stack trace: ...

❌ Lỗi nghiêm trọng:
• getUserIdFromPageId() trả về NULL
• Không thể lưu vào database
• Bot crash, không phản hồi
• Fix: Cập nhật getUserIdFromPageId() query từ facebook_pages

🎯 Khi Nào Dùng Log Nào?

Decision Tree - Chọn Log File

Bạn gặp vấn đề gì?

↓

❌ Webhook không nhận tin nhắn

→ Dùng webhook_requests.log

Gửi tin nhắn
Check log có data không
Nếu KHÔNG → Fix webhook config
Nếu CÓ → Chuyển sang check processing log

❌ Bot không phản hồi

→ Dùng webhook_processing_debug.log

Check user_id có được resolve không
Check keyword có match không
Check database có lỗi không
Check response type

Use Cases Chi Tiết

📥 Dùng webhook_requests.log

Verify webhook có hoạt động không
Check event types (message, delivery, read, postback)
Debug sender_id và page_id
Verify message text content
Check Facebook có gửi duplicate webhooks không
Debug postback payloads
Verify echo messages có is_echo flag

🔧 Dùng webhook_processing_debug.log

Debug user_id lookup failure
Check duplicate message detection
Debug keyword matching logic
Trace script execution flow
Find database errors
Debug AI responses (ChatGPT/Gemini)
Check filter logic (echo, page messages)
Monitor response types (silent, script, multi_step)

🔍 Quy Trình Debug

Workflow Debug Từng Bước

Bước 1: Verify Webhook Connection

Tool: webhook_requests.log

tail -f webhook_requests.log

Gửi tin nhắn vào page → Check log có xuất hiện không

✅ Có log → Webhook OK, chuyển bước 2
❌ Không có log → Fix webhook config trong Facebook App

Bước 2: Check Event Type

Tool: webhook_requests.log

grep '"message"' webhook_requests.log

Verify event type có phải là message không

✅ Event = "message" → OK, chuyển bước 3
⚠️ Event = "delivery", "read" → Bot không xử lý, normal behavior

Bước 3: Check Processing Started

Tool: webhook_processing_debug.log

tail -f webhook_processing_debug.log

Gửi tin nhắn → Check có log "PROCESSING TEXT MESSAGE" không

✅ Có log → Processing started, chuyển bước 4
❌ Không có log → Message bị filter (echo, delivery, etc.)

Bước 4: Verify User ID Resolution

Tool: webhook_processing_debug.log

grep "User ID:" webhook_processing_debug.log

✅ "User ID: 36" → OK, chuyển bước 5
❌ "User ID: NULL" → Fix getUserIdFromPageId() function

Bước 5: Check Database Save

Tool: webhook_processing_debug.log

grep "Insert result:" webhook_processing_debug.log

✅ "Insert result: SUCCESS" → OK, chuyển bước 6
❌ "EXCEPTION" → Check database constraints, user_id

Bước 6: Check Response Type

Tool: webhook_processing_debug.log

grep "Response type:" webhook_processing_debug.log

✅ "script" / "multi_step" → Bot đã phản hồi
⚠️ "silent" → Không match keyword, cần add keyword hoặc bật AI
✅ "chatgpt" / "gemini" → AI đã phản hồi

💻 Lệnh Thường Dùng

📥 webhook_requests.log

Monitor realtime:

tail -f webhook_requests.log

Xem 50 dòng cuối:

tail -50 webhook_requests.log

Tìm message events:

grep '"message"' webhook_requests.log

Tìm postback events:

grep '"postback"' webhook_requests.log

Filter echo messages:

grep '"is_echo":true' webhook_requests.log

Đếm messages từ sender:

grep '"sender":{"id":"24502905"' webhook_requests.log | wc -l

🔧 webhook_processing_debug.log

Monitor realtime:

tail -f webhook_processing_debug.log

Tìm errors:

grep "EXCEPTION" webhook_processing_debug.log

Tìm user_id NULL:

grep "User ID: NULL" webhook_processing_debug.log

Tìm silent responses:

grep "Response type: silent" webhook_processing_debug.log

Tìm multi-step executions:

grep "Response type: multi_step" webhook_processing_debug.log

Tìm database errors:

grep "Insert result: FAILED" webhook_processing_debug.log

Lệnh Kết Hợp

Monitor cả 2 logs cùng lúc:

# Terminal 1
tail -f webhook_requests.log

# Terminal 2  
tail -f webhook_processing_debug.log

Tìm tin nhắn cụ thể trong cả 2 logs:

# Tìm message ID trong webhook_requests.log
grep "m_27Lh0z" webhook_requests.log

# Tìm cùng message ID trong processing log
grep "m_27Lh0z" webhook_processing_debug.log

Extract message texts:

# Từ webhook_requests.log
grep -o '"text":"[^"]*"' webhook_requests.log

# Từ processing log
grep "Message:" webhook_processing_debug.log

Rotate logs khi quá lớn:

# Backup logs
mv webhook_requests.log webhook_requests_backup_$(date +%Y%m%d).log
mv webhook_processing_debug.log webhook_processing_debug_backup_$(date +%Y%m%d).log

# Hoặc clear logs (cẩn thận!)
> webhook_requests.log
> webhook_processing_debug.log

🛠️ Troubleshooting Scenarios

Scenario 1: "Bot hoàn toàn không phản hồi"

❌ Triệu chứng

User gửi tin nhắn nhưng bot im lặng hoàn toàn

🔍 Debug Steps:

Step 1: Check webhook_requests.log

tail -f webhook_requests.log

Gửi tin nhắn test → Có log không?

❌ KHÔNG có log → Webhook chưa được config
✅ CÓ log → Chuyển step 2

Step 2: Verify event type

grep '"message"' webhook_requests.log | tail -1

✅ Có "message" → Chuyển step 3
⚠️ Chỉ có "delivery" → Normal, không phải message text

Step 3: Check webhook_processing_debug.log

tail -f webhook_processing_debug.log

✅ Có "PROCESSING TEXT MESSAGE" → Chuyển step 4
❌ Không có → Message bị filter hoặc không phải text

Step 4: Check User ID

grep "User ID:" webhook_processing_debug.log | tail -1

✅ "User ID: 36" → Chuyển step 5
❌ "User ID: NULL" → Fix getUserIdFromPageId()

Step 5: Check Response Type

grep "Response type:" webhook_processing_debug.log | tail -1

✅ "script" / "multi_step" → Bot đã phản hồi (check Facebook app)
⚠️ "silent" → Không match keyword, add keyword hoặc bật AI

Scenario 2: "Bot phản hồi sai nội dung"

⚠️ Triệu chứng

Bot phản hồi nhưng nội dung không đúng với script đã config

🔍 Debug Steps:

Step 1: Verify user_id

grep "User ID:" webhook_processing_debug.log | tail -1

Check user_id có đúng không

User 36 phải phản hồi scripts của user 36
Nếu sai user_id → Data isolation failure

Step 2: Check script_used_id

SELECT * FROM conversations WHERE sender_id = '...' ORDER BY created_at DESC LIMIT 1;

Xem script_used_id là bao nhiêu

Step 3: Verify script content

SELECT * FROM bot_scripts WHERE id = [script_used_id];

Check nội dung script có đúng không

Scenario 3: "Bot phản hồi chậm"

⚠️ Triệu chứng

Bot phản hồi nhưng mất 5-10 giây

🔍 Debug Steps:

Check timestamps

So sánh timestamps giữa 2 logs:

# webhook_requests.log
Time: 2026-02-10 19:24:09

# webhook_processing_debug.log
=== [2026-02-10 19:24:09] ===
...
✅ Processing completed successfully

Tính thời gian từ nhận webhook đến hoàn thành

Identify bottleneck

AI response (ChatGPT/Gemini) → Có thể mất 2-5s
Multi-step với delay → Check delay_seconds
Database slow query → Optimize queries

💡 Best Practices

Log Management

Monitor logs realtime khi testing: tail -f
Rotate logs định kỳ khi file > 10MB
Backup logs trước khi clear
Dùng grep để filter noise (delivery, read events)
Combine cả 2 logs để có full picture
Archive logs theo tháng để troubleshoot sau này

Debugging Workflow

Luôn check webhook_requests.log TRƯỚC
Verify webhook có nhận data từ Facebook
Check event type (message vs delivery vs read)
Sau đó mới check webhook_processing_debug.log
Trace từng bước: user_id → database → matching → response
Document issues found để tránh lặp lại

Monitoring in Production

Setup cron job để auto-rotate logs
Alert khi có EXCEPTION trong processing log
Monitor file size của logs
Periodic check cho "User ID: NULL" errors
Track response type distribution (script vs silent vs AI)
Archive logs cho compliance/audit

⚡ Quick Reference

Tình Huống	Log Cần Dùng	Lệnh
Webhook không hoạt động	webhook_requests.log	`tail -f webhook_requests.log`
Bot không phản hồi	webhook_processing_debug.log	`grep "Response type:" ...`
Check user_id resolution	webhook_processing_debug.log	`grep "User ID:" ...`
Verify event type	webhook_requests.log	`grep '"message"' ...`
Find database errors	webhook_processing_debug.log	`grep "EXCEPTION" ...`
Check echo messages	webhook_requests.log	`grep '"is_echo":true' ...`
Monitor keyword matching	webhook_processing_debug.log	`grep "Response type: script" ...`
Check postback payloads	webhook_requests.log	`grep '"postback"' ...`

📝 Tổng Kết

📥 webhook_requests.log

Khi nào dùng:

✅ Webhook không hoạt động
✅ Verify connectivity
✅ Debug event types
✅ Check sender/page ID

Câu hỏi trả lời:

"Webhook có nhận data từ Facebook không?"

🔧 webhook_processing_debug.log

Khi nào dùng:

✅ Bot không phản hồi
✅ Debug business logic
✅ Find code errors
✅ Trace workflow

Câu hỏi trả lời:

"Bot xử lý tin nhắn như thế nào?"

🎯 Nguyên Tắc Vàng

2 logs BỔ SUNG cho nhau, KHÔNG thay thế!
Luôn check webhook_requests.log trước để verify data đến server,
sau đó check webhook_processing_debug.log để verify bot xử lý đúng.

📊 Webhook Logs Documentation

🎯 Tổng Quan

2 Log Files Chính

📥 webhook_requests.log

🔧 webhook_processing_debug.log

📊 So Sánh Chi Tiết

📝 Ví Dụ Chi Tiết

Example 1: Text Message từ User

📥 webhook_requests.log

🔧 webhook_processing_debug.log

Example 2: Delivery Receipt (KHÔNG phải tin nhắn)

📥 webhook_requests.log

🔧 webhook_processing_debug.log

Example 3: Echo Message (Tin nhắn của chính bot)

📥 webhook_requests.log

🔧 webhook_processing_debug.log

Example 4: Lỗi - User ID NULL

📥 webhook_requests.log

🔧 webhook_processing_debug.log

🎯 Khi Nào Dùng Log Nào?

Decision Tree - Chọn Log File

❌ Webhook không nhận tin nhắn

❌ Bot không phản hồi

Use Cases Chi Tiết

📥 Dùng webhook_requests.log

🔧 Dùng webhook_processing_debug.log

🔍 Quy Trình Debug

Workflow Debug Từng Bước

Bước 1: Verify Webhook Connection

Bước 2: Check Event Type

Bước 3: Check Processing Started

Bước 4: Verify User ID Resolution

Bước 5: Check Database Save

Bước 6: Check Response Type

💻 Lệnh Thường Dùng

📥 webhook_requests.log

Monitor realtime:

Xem 50 dòng cuối:

Tìm message events:

Tìm postback events:

Filter echo messages:

Đếm messages từ sender:

🔧 webhook_processing_debug.log

Monitor realtime:

Tìm errors:

Tìm user_id NULL:

Tìm silent responses:

Tìm multi-step executions:

Tìm database errors:

Lệnh Kết Hợp

Monitor cả 2 logs cùng lúc:

Tìm tin nhắn cụ thể trong cả 2 logs:

Extract message texts:

Rotate logs khi quá lớn:

🛠️ Troubleshooting Scenarios

Scenario 1: "Bot hoàn toàn không phản hồi"

❌ Triệu chứng

🔍 Debug Steps:

Step 1: Check webhook_requests.log

Step 2: Verify event type

Step 3: Check webhook_processing_debug.log

Step 4: Check User ID

Step 5: Check Response Type

Scenario 2: "Bot phản hồi sai nội dung"

⚠️ Triệu chứng

🔍 Debug Steps:

Step 1: Verify user_id

Step 2: Check script_used_id

Step 3: Verify script content

Scenario 3: "Bot phản hồi chậm"

⚠️ Triệu chứng

🔍 Debug Steps:

Check timestamps

Identify bottleneck

💡 Best Practices

Log Management

Debugging Workflow

Monitoring in Production

⚡ Quick Reference

📝 Tổng Kết