# Xử lý Webhook Đa nền tảng (Deep Dive)

Hệ thống Social Inbox của Canifa tiếp nhận dữ liệu thời gian thực thông qua các Webhook endpoint chuyên biệt cho từng mạng xã hội (Facebook, Instagram, TikTok) bằng FastAPI.

## Kiến trúc Luồng Dữ liệu (Logic Flow)

Dưới đây là quy trình xử lý từ khi có sự kiện (comment/DM/mention) xảy ra trên mạng xã hội cho đến khi hệ thống lưu trữ và đẩy vào Feedback Tracker:

```mermaid
sequenceDiagram
    participant Social as Facebook/IG/TikTok
    participant Router as Social Inbox Route
    participant Parser as Webhook Parser
    participant Sentiment as Sentiment Analyzer
    participant DB as JSON Storage
    participant Tracker as Feedback Tracker
    
    Social->>Router: POST /webhook/{platform}
    Note over Router: Verify HMAC Signature
    Router->>Parser: parse_webhook(payload)
    
    loop For each event/message
        Parser->>Sentiment: analyze_sentiment(body)
        Sentiment-->>Parser: Result (positive/negative/neutral)
        Parser-->>Router: Normalized SocialMessage
    end
    
    Router->>DB: append_messages() & deduplicate
    Router->>Tracker: BackgroundTask: _feed_to_feedback_tracker()
    Router-->>Social: 200 OK {"ok": true, "received": n}
```

## Chi tiết Kỹ thuật (Theo source code thực tế)

### 1. Facebook & Instagram Webhook (`/api/social/webhook/facebook`)
*   **Verification (GET Handshake):** Xử lý yêu cầu xác minh từ Facebook bằng cách so sánh `hub.verify_token` với biến môi trường `FACEBOOK_WEBHOOK_VERIFY_TOKEN`.
*   **Signature Verification:** Kiểm tra tính hợp lệ của payload thông qua header `X-Hub-Signature-256`. Webhook Parser sử dụng thuật toán `HMAC-SHA256` với khóa bí mật `FACEBOOK_APP_SECRET` để xác thực, từ chối mọi payload bị giả mạo.
*   **Parsing Payload:** Module `parse_facebook_webhook` (trong `inbox_webhook.py`) hỗ trợ bóc tách 3 loại events:
    *   **Feed Changes:** Comments trên các bài post (hỗ trợ cả Facebook và Instagram dựa vào trường `item`).
    *   **Mentions:** Bắt các sự kiện khi fanpage/account bị gắn thẻ.
    *   **Messaging:** Tin nhắn trực tiếp (Direct Messages - DM).

### 2. TikTok Webhook (`/api/social/webhook/tiktok`)
*   Nhận và bóc tách trực tiếp các **comment notifications** từ cấu trúc `payload.get("data", {}).get("comments", [])` theo chuẩn webhook riêng của TikTok.

### 3. Chuẩn hóa & Cấu trúc lưu trữ
*   **Normalization:** Mọi payload đặc thù của từng nền tảng đều được trích xuất và chuẩn hóa về định dạng chung `SocialMessage` chứa: `platform`, `message_type` (comment/mention/dm), `sender_name`, `sender_id`, `body`, `post_id`, và `sentiment`.
*   **Deduplication:** Các tin nhắn được chống trùng lặp dựa vào cặp khóa `(platform, body)`.
*   **Storage:** Do tính chất lightweight, hệ thống lưu trữ dạng in-memory list rồi tự động serialize ra file vật lý `social_messages.json`. Sức chứa bị giới hạn tối đa **500 messages** gần nhất (xóa vòng lặp theo kiểu queue) để đảm bảo tốc độ dashboard không bị suy giảm.