Hướng dẫn cấu hình Webhook

Webhook là gì?

Webhook cho phép SNSTracker tự động gửi thông báo đến máy chủ hoặc ứng dụng của bạn khi nội dung được theo dõi đạt các ngưỡng bạn đã cấu hình. Ví dụ, khi lượt xem của một video tăng đáng kể hoặc khi một kênh có thêm người theo dõi mới, SNSTracker sẽ gửi thông báo đến URL webhook của bạn (thường trong vòng 1 phút).

Hướng dẫn cấu hình từng bước

Bước 1: Chuẩn bị endpoint webhook

Trước khi cấu hình trong SNSTracker, bạn cần có sẵn một endpoint webhook. Đây là một URL có thể nhận yêu cầu HTTP POST.

Các lựa chọn cho endpoint webhook của bạn:

Máy chủ riêng của bạn: https://api.yourcompany.com/webhook
Cloud functions: AWS Lambda, Google Cloud Functions, Azure Functions, v.v.
Nền tảng tự động hóa: Zapier, Make.com, n8n, v.v.
Dịch vụ kiểm thử: webhook.site (chỉ dùng để kiểm thử)

Yêu cầu:

Phải dùng HTTPS (URL bắt đầu bằng https://)
Phải chấp nhận yêu cầu POST
Nên trả về mã trạng thái HTTP 200-299 khi thành công

Bước 2: Thêm webhook target trong SNSTracker

Đi tới trang Collections
- Đăng nhập vào SNSTracker
- Nhấp Collections ở thanh bên trái (trong mục Track)
- Hoặc truy cập trực tiếp: /dashboard/collections
Mở Manage Notify Targets
- Trên trang Collections, tìm và nhấp nút "Manage Notify Targets"
- Thao tác này sẽ mở hộp thoại quản lý các notify target
Thêm target mới
- Nhấp nút "Add Target"
- Một hộp thoại sẽ xuất hiện để tạo notify target mới
Chọn loại Webhook
- Trong hộp thoại, tìm menu thả xuống "Type"
- Chọn "Webhook" từ các tùy chọn
Nhập URL Webhook
- Trong trường "Webhook URL", nhập URL endpoint webhook của bạn
- Ví dụ: https://api.yourcompany.com/webhook
- Quan trọng: URL phải bắt đầu bằng https://
Thêm ghi chú (tùy chọn)
- Trong trường "Comment", bạn có thể thêm ghi chú để nhớ webhook này dùng cho việc gì
- Ví dụ: "Webhook production cho theo dõi TikTok"
- Tối đa 50 ký tự
Cấu hình khóa chữ ký (tùy chọn, khuyến nghị cho môi trường production)
- Trong trường "Extra", bạn có thể thêm một đối tượng JSON với khóa chữ ký:
```
{
  "signature_key": "your-secret-key-here"
}
```
- Khóa này sẽ dùng để xác minh yêu cầu là xác thực
- Nếu không cung cấp, SNSTracker sẽ dùng API key hoặc URL webhook của bạn làm khóa chữ ký
Lưu webhook target
- Nhấp nút "Save"
- Webhook target của bạn đã được tạo và sẵn sàng sử dụng

Bước 3: Cấu hình quy tắc thông báo trong Collection

Mở cài đặt Collection
- Quay lại trang Collections
- Tìm collection mà bạn muốn cấu hình thông báo
- Nhấp nút Edit (hoặc nhấp vào tên collection để mở cài đặt)
Bật Feed Notify (cho video/bài đăng)
- Trong cài đặt collection, tìm phần "Feed Notify"
- Bật công tắc "Enable Notifications" sang ON
- Chọn webhook target từ menu thả xuống "Notify Targets"
- Chọn "Metrics" bạn muốn theo dõi:
  - Lượt xem
  - Tương tác (lượt thích + bình luận + chia sẻ)
- Đặt giá trị "Threshold":
  - Nhập một số (ví dụ: 1000) để thông báo khi chỉ số tăng thêm mức này
  - Đặt về 0 để thông báo sau mỗi lần làm mới thành công
- Nhấp "Save" hoặc "Update"
Bật Channel Notify (cho tài khoản)
- Trong cùng cài đặt collection, tìm phần "Channel Notify"
- Bật công tắc "Enable Notifications" sang ON
- Chọn webhook target từ menu thả xuống "Notify Targets"
- Chọn "Metrics" bạn muốn theo dõi:
  - Người theo dõi
  - Đang theo dõi
  - Lượt thích
- Đặt giá trị "Threshold":
  - Nhập một số (ví dụ: 500) để thông báo khi chỉ số tăng thêm mức này
  - Đặt về 0 để thông báo sau mỗi lần làm mới thành công
- Nhấp "Save" hoặc "Update"
Xác minh cấu hình
- Đảm bảo cả webhook target và quy tắc thông báo đều đã được lưu
- Webhook của bạn sẽ nhận thông báo khi các ngưỡng đã cấu hình được đáp ứng

Bước 4: Kiểm thử webhook

Dùng dịch vụ kiểm thử (khuyến nghị cho lần thiết lập đầu tiên)
- Truy cập webhook.site
- Sao chép URL duy nhất được cung cấp (ví dụ: https://webhook.site/unique-id)
- Dùng URL này làm webhook URL ở Bước 2
- Cấu hình thông báo với ngưỡng 0 (để kích hoạt khi có bất kỳ thay đổi nào)
- Chờ SNSTracker kiểm tra nội dung của bạn
- Kiểm tra webhook.site để xem bạn đã nhận được thông báo chưa
Kiểm tra log endpoint của bạn
- Nếu dùng máy chủ riêng, hãy kiểm tra log máy chủ
- Tìm các yêu cầu POST đến từ SNSTracker
- Xác minh phần thân yêu cầu có dữ liệu như mong đợi
Xác minh định dạng thông báo
- Thông báo phải là một đối tượng JSON với:
  - title: Mô tả thông báo
  - type: "feed" hoặc "channel"
  - timestamp: Thời điểm gửi thông báo
  - data: Mảng các mục đã kích hoạt thông báo

Cách SNSTracker gửi thông báo webhook

SNSTracker sử dụng cơ chế gom lô để tối ưu việc gửi webhook:

Phát hiện ngay lập tức: Khi một tài nguyên được theo dõi (feed hoặc channel) được làm mới thành công và đạt ngưỡng thông báo, nó sẽ được đánh dấu để gửi thông báo ngay.
Cửa sổ gom lô 1 phút: Thay vì gửi từng thông báo ngay lập tức, SNSTracker sẽ gom tất cả các thông báo đủ điều kiện trong một cửa sổ 1 phút.
Gửi gộp: Ở cuối mỗi khoảng 1 phút, tất cả thông báo trong khoảng đó sẽ được gộp vào một yêu cầu webhook duy nhất và gửi cùng lúc.

Ví dụ tình huống:

Lúc 10:00:15, Feed A đạt ngưỡng → được đánh dấu
Lúc 10:00:45, Feed B đạt ngưỡng → được đánh dấu
Lúc 10:01:00, cả Feed A và Feed B được gửi trong một yêu cầu webhook

Lợi ích:

Giảm số lượng yêu cầu HTTP đến endpoint của bạn
Tăng hiệu quả và giảm tải máy chủ
Tránh spam thông báo khi dữ liệu thay đổi nhanh
Tất cả thông báo trong khoảng gom lô sẽ được đưa vào mảng data

Lưu ý: Độ trễ tối đa giữa lúc tài nguyên đạt ngưỡng và webhook được gửi là 1 phút. Điều này đảm bảo thông báo gần như theo thời gian thực đồng thời vẫn duy trì hiệu suất hệ thống.

Bạn sẽ nhận được dữ liệu gì?

Khi một thông báo được kích hoạt, bạn sẽ nhận một yêu cầu POST với dữ liệu JSON như sau:

{
  "title": "SNSTracker Notification: Feed Views Increased",
  "type": "feed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": [
    {
      "feed_id": "feed-123",
      "url": "https://www.tiktok.com/@user/video/123",
      "platform_name": "TikTok",
      "view_count": 10000,
      "like_count": 2000,
      "changed_views": 1000,
      "changed_engagement": 50
    }
  ]
}

Các trường dữ liệu thông báo Feed

feed_id: Mã định danh duy nhất
url: Liên kết trực tiếp tới video/bài đăng
platform_name: Nền tảng (TikTok, Instagram, v.v.)
title: Tiêu đề nội dung
description: Mô tả nội dung
author_username: Tên người dùng của creator
author_nickname: Tên hiển thị của creator
view_count: Tổng lượt xem
like_count: Tổng lượt thích
comment_count: Tổng bình luận
share_count: Tổng lượt chia sẻ
changed_views: Lượt xem tăng kể từ lần kiểm tra trước
changed_engagement: Tương tác tăng (lượt thích + bình luận + chia sẻ)

Các trường dữ liệu thông báo Channel

id: Mã định danh duy nhất của kênh
channel_url: Liên kết trực tiếp tới kênh/profile
platform_name: Tên nền tảng
nickname: Tên hiển thị
username: Tên người dùng/handle
followers: Tổng người theo dõi
followings: Tổng tài khoản đang theo dõi
likes: Tổng lượt thích
changed_followers: Người theo dõi tăng kể từ lần kiểm tra trước
changed_followings: Đang theo dõi tăng kể từ lần kiểm tra trước
changed_likes: Lượt thích tăng kể từ lần kiểm tra trước

Bảo mật: Xác minh chữ ký

SNSTracker bao gồm chữ ký trong header X-Signature để xác minh tính xác thực của yêu cầu. Khóa chữ ký được xác định bởi:

signature_key trong trường Extra (nếu có)
API key đang hoạt động đầu tiên của bạn (nếu không đặt signature_key)
URL webhook của bạn (làm phương án dự phòng)

Đối với môi trường production, bạn nên xác minh chữ ký để đảm bảo các yêu cầu là xác thực.

Khắc phục sự cố

Webhook không nhận được thông báo

Kiểm tra URL webhook
- Xác minh URL chính xác và có thể truy cập
- Đảm bảo bắt đầu bằng https://
- Thử URL thủ công bằng một yêu cầu POST
Kiểm tra cài đặt thông báo
- Xác minh thông báo đã được bật trong Collection
- Kiểm tra webhook target đã được chọn
- Đảm bảo ngưỡng được đặt đúng
Kiểm tra trạng thái endpoint
- Đảm bảo endpoint của bạn đang chạy và có thể truy cập
- Kiểm tra log máy chủ để thấy các yêu cầu đến
- Xác minh endpoint trả về trạng thái thành công (200-299)

Các vấn đề thường gặp

Vấn đề: "Webhook URL already exists"
Giải pháp: Mỗi URL webhook chỉ có thể được dùng một lần trong mỗi team. Hãy dùng URL khác hoặc chỉnh sửa target hiện có.

Vấn đề: Thông báo không được kích hoạt
Giải pháp:

Đặt ngưỡng về 0 để kiểm thử (thông báo khi có bất kỳ thay đổi nào)
Chờ SNSTracker kiểm tra nội dung của bạn (việc kiểm tra diễn ra định kỳ)
Xác minh nội dung của bạn thực sự thay đổi đúng mức ngưỡng

Vấn đề: Lỗi timeout
Giải pháp: Endpoint của bạn phải phản hồi trong vòng 30 giây. Hãy tối ưu thời gian phản hồi của endpoint.

Cần hỗ trợ?

Nếu bạn gặp sự cố:

Xác minh URL webhook của bạn có thể truy cập
Kiểm tra cài đặt thông báo đã được bật
Đảm bảo ngưỡng đã được cấu hình đúng
Liên hệ hỗ trợ nếu vấn đề vẫn tiếp diễn

Theo dõi vui vẻ! 🚀

Hướng dẫn cấu hình Webhook

On this page