Echobell
App Store Google Play

Tích hợp Webhook - Hướng dẫn đầy đủ về kích hoạt qua HTTP

Tích hợp webhook Echobell: phương thức HTTP, biến, mẫu, header và ví dụ thực tế để nhận cảnh báo tức thì trên điện thoại.

Webhook là cách linh hoạt nhất để kích hoạt thông báo Echobell. Hướng dẫn toàn diện này bao quát mọi thứ bạn cần biết để đưa cảnh báo dựa trên webhook vào hệ thống của mình, từ khái niệm cơ bản đến các cách dùng nâng cao.

Webhook là gì

Webhook là cách để một ứng dụng cung cấp thông tin theo thời gian thực cho ứng dụng khác thông qua HTTP callback. Bạn có thể hình dung nó như một số điện thoại mà bạn đưa cho ai đó - khi họ gọi vào số ấy, điện thoại của bạn reo. Trong thế giới số, khi có chuyện xảy ra ở một hệ thống (như CPU tăng cao, một lần build thất bại, hay một đơn hàng mới), hệ thống đó gửi một HTTP request tới URL (chính là webhook) mà bạn đã cung cấp, qua đó kích hoạt một hành động trong hệ thống của bạn.

Ví dụ, khi mức sử dụng CPU trên máy chủ của bạn lên quá cao, hệ thống giám sát có thể gọi tới webhook URL của Echobell, và Echobell sẽ kích hoạt một thông báo để cảnh báo bạn. Việc này diễn ra tự động và theo thời gian thực, bạn không phải liên tục tự kiểm tra mức sử dụng CPU.

Webhook là nền tảng của các kiến trúc hướng sự kiện và được hỗ trợ bởi gần như mọi dịch vụ cloud, công cụ giám sát và nền tảng SaaS hiện đại. Chúng nhẹ, nhanh và không đòi hỏi hạ tầng đặc biệt nào ở phía bạn - chỉ cần một HTTP client.

Lợi ích của Webhook

  • Thời gian thực: Sự kiện kích hoạt thông báo ngay lập tức, thường trong vòng 1-2 giây
  • Phổ biến: Được hỗ trợ bởi gần như mọi dịch vụ và ngôn ngữ lập trình hiện đại
  • Linh hoạt: Truyền dữ liệu tùy ý để tạo thông báo giàu thông tin, đúng bối cảnh
  • Đáng tin cậy: Dựa trên HTTP, với mã trạng thái chuẩn và cách xử lý lỗi rõ ràng
  • Dễ mở rộng: Không cần polling - thông báo chỉ được gửi khi có sự kiện xảy ra

Tổng quan

Mỗi kênh Echobell có thể được cấu hình với một webhook URL riêng. Khi URL này được gọi, kênh sẽ gửi thông báo tới toàn bộ người đăng ký dựa trên mẫu thông báo đã cấu hình và các biến được cung cấp.

Định dạng webhook URL

https://hook.echobell.one/t/{channel-token}

Bạn có thể tìm thấy webhook URL của kênh trong màn hình chi tiết kênh của ứng dụng Echobell.

Gửi request webhook

Webhook của Echobell hỗ trợ cả phương thức GET lẫn POST:

Request GET

Bạn có thể truyền biến qua tham số query:

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

Request POST

Với request POST, hãy gửi biến trong body JSON:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

POST Only

Mỗi kênh có một công tắc POST Only trong mục Advanced Settings của ứng dụng Echobell. Mặc định nó đang tắt.

Khi bật, chỉ POST mới kích hoạt được kênh. Một request GET tới webhook URL sẽ bị từ chối với mã 405 Method Not Allowed, và không có thông báo nào được gửi:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

Request HEAD không bị ảnh hưởng — chúng luôn trả về 200 và không bao giờ kích hoạt thông báo, dù POST Only bật hay tắt.

Hãy bật tùy chọn này khi webhook URL có thể lọt vào nơi tự động tải trước liên kết — một tin nhắn chat, một trang wiki, thanh địa chỉ trình duyệt — để việc xem trước hay mở URL không thể làm bùng một cảnh báo. Hãy để tắt nếu có bất kỳ bên gọi nào kích hoạt kênh bằng GET.

Biến đặc biệt

Echobell hỗ trợ một biến đặc biệt giúp bổ sung tính năng cho thông báo của bạn:

  • externalLink: Khi có trong request, biến này tạo một liên kết bấm được trong màn hình xem bản ghi thông báo. Rất hữu ích để trỏ tới thông tin chi tiết hoặc tài nguyên liên quan.

Ví dụ có kèm liên kết ngoài:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Biến trong mẫu

Các biến truyền qua webhook có thể được dùng trong mẫu thông báo của bạn theo cú pháp {{variableName}}:

Title: Server {{server_name}} Alert
Body: CPU usage has reached {{cpu_usage}}%

Khi được kích hoạt, những mẫu này sẽ được điền bằng các giá trị bạn cung cấp trong request webhook.

Biến thời gian hệ thống (UTC)

Ngoài dữ liệu bạn gửi lên, Echobell còn cung cấp các biến thời gian hệ thống chỉ đọc, luôn có sẵn trong mẫu và điều kiện. Mọi giá trị đều được tính theo UTC. Các trường phẳng gồm date, time, year, month, dayOfWeek, hour, minute và second. Một số biến khác — như sys.dayOfWeekName, sys.epochMs và sys.epochSeconds — chỉ có trong không gian tên sys.. Xem Điều kiện để biết danh sách đầy đủ và ví dụ.

Các trường hợp sử dụng phổ biến

Webhook là cách kích hoạt được dùng nhiều nhất trong Echobell, đặc biệt hữu ích cho:

DevOps và giám sát

  • Giám sát máy chủ: Cảnh báo về CPU, bộ nhớ, dung lượng đĩa từ các hệ thống giám sát như Prometheus hoặc Grafana
  • Giám sát uptime: Cảnh báo về tình trạng hoạt động của website và dịch vụ từ Uptime Kuma hoặc UptimeRobot
  • Giám sát container: Docker, pod Kubernetes gặp lỗi và các giới hạn tài nguyên
  • Gom log: Lỗi và exception nghiêm trọng từ các hệ thống quản lý log

Phát triển và CI/CD

  • Thông báo build: Build thất bại, kết quả test, trạng thái triển khai từ GitHub Actions hoặc GitLab CI
  • Chất lượng mã: Lỗi lint, lỗ hổng bảo mật, thay đổi độ phủ test
  • Sự kiện kho mã: Pull request, commit, release và hoạt động của cộng tác viên
  • Theo dõi triển khai: Triển khai thành công, rollback và thay đổi môi trường

Ứng dụng nghiệp vụ

  • Thương mại điện tử: Đơn hàng mới, xác nhận thanh toán, cảnh báo tồn kho, cập nhật vận chuyển
  • CRM: Khách hàng tiềm năng mới, chốt hợp đồng, ticket hỗ trợ, tương tác khách hàng
  • Xử lý thanh toán: Giao dịch hoàn tất, yêu cầu hoàn tiền, cảnh báo gian lận
  • Gửi biểu mẫu: Biểu mẫu liên hệ, phản hồi khảo sát, hoàn tất đăng ký

IoT và nhà thông minh

  • Sự kiện nhà thông minh: Cảm biến cửa, phát hiện chuyển động, thay đổi nhiệt độ qua Home Assistant
  • Thiết bị IoT: Số đo cảm biến, thay đổi trạng thái thiết bị, sự cố kết nối
  • Hệ thống an ninh: Báo động kích hoạt, camera phát hiện chuyển động, sự kiện kiểm soát ra vào
  • Giám sát môi trường: Nhiệt độ, độ ẩm, chất lượng không khí vượt ngưỡng

Giao dịch và tài chính

  • Cảnh báo thị trường: Biến động giá, chỉ báo kỹ thuật từ TradingView
  • Giám sát danh mục: Thay đổi vị thế, lệnh gọi ký quỹ, số dư tài khoản
  • Sự kiện kinh tế: Tin tức công bố, báo cáo lợi nhuận, thay đổi tâm lý thị trường

Xem các hướng dẫn tích hợp để biết cách thiết lập cụ thể cho những nền tảng phổ biến.

Thực hành tốt nhất

Xử lý lỗi

Đừng chỉ dựa vào mã trạng thái HTTP — hãy luôn xem body JSON trả về và kiểm tra trường success:

  • 200 OK: Request đã được tiếp nhận. Hãy kiểm tra body JSON: success: true nghĩa là kênh đã được kích hoạt, còn success: false nghĩa là request được chấp nhận nhưng không có thông báo nào được gửi (ví dụ, token kênh không tồn tại — trường hợp này vẫn trả về HTTP 200).
  • 400 Bad Request: Token kênh sai độ dài. Hãy sửa lại webhook URL.
  • 405 Method Not Allowed: Kênh đang bật POST Only mà request lại không phải POST. Hãy chuyển bên gọi sang POST, hoặc tắt tùy chọn này.
  • 500 Server Error: Sự cố tạm thời, hãy thử lại với thời gian chờ tăng dần

Echobell không giới hạn tần suất gọi webhook, nên không có phản hồi 429. Vì một token không tồn tại (nhưng đúng độ dài) vẫn trả về 200 kèm success: false, hãy luôn rẽ nhánh theo trường success trong JSON thay vì theo mã trạng thái HTTP.

Giới hạn tần suất

Hãy giãn cách hợp lý giữa các lần gọi webhook để không làm quá tải hệ thống thông báo của bạn:

  • Với giám sát liên tục, hãy gộp nhiều sự kiện vào một thông báo
  • Dùng điều kiện để lọc bỏ những sự kiện không quan trọng
  • Cân nhắc gom lại các sự kiện dồn dập (ví dụ, nhiều lỗi trong thời gian ngắn)
  • Tránh gửi liên tiếp những lần kích hoạt trùng lặp để giữ cho cảnh báo quan trọng luôn đáng tin cậy

Bảo mật dữ liệu

Chỉ chia sẻ webhook URL với những hệ thống và dịch vụ đáng tin cậy:

  • Hãy coi webhook URL là thông tin bí mật - chúng cho phép gửi thông báo trực tiếp
  • Đừng đưa webhook URL lên kho mã công khai hay chia sẻ trong tài liệu công khai
  • Định kỳ đổi mới webhook URL, hoặc đổi khi có thành viên rời nhóm
  • Dùng tính năng "Reset Token" của kênh để vô hiệu hóa các URL cũ nếu bị lộ
  • Cân nhắc dùng biến môi trường hoặc hệ thống quản lý bí mật để lưu các URL

Đặt tên biến

Hãy dùng tên biến rõ ràng và nhất quán trong các lần gọi webhook:

  • Dùng tên mang tính mô tả: server_name thay vì s hay srv
  • Theo một quy ước đặt tên thống nhất trên mọi kênh
  • Ghi lại những biến mà mẫu của bạn cần
  • Kiểm tra rằng mọi biến bắt buộc đều có mặt trước khi gửi

Kiểm thử

Hãy kiểm thử kỹ phần tích hợp webhook trước khi đưa vào production:

  1. Dùng các công cụ như curl, Postman hoặc HTTP client của ngôn ngữ bạn dùng để thử ban đầu
  2. Bắt đầu với mẫu đơn giản rồi tăng dần độ phức tạp
  3. Thử cả phương thức GET lẫn POST để tìm cách phù hợp nhất
  4. Kiểm tra xem ký tự đặc biệt và Unicode có được xử lý đúng không
  5. Thử các tình huống lỗi (thiếu biến, JSON sai định dạng) để hiểu cách hệ thống phản ứng
  6. Dùng kênh thử nghiệm tách biệt với kênh production trong lúc phát triển

Thiết kế mẫu

Hãy thiết kế mẫu sao cho vẫn hữu ích ngay cả khi thiếu biến tùy chọn:

  • Cung cấp giá trị mặc định hoặc phương án dự phòng cho dữ liệu tùy chọn
  • Cấu trúc mẫu sao cho xử lý êm thấm khi thiếu biến
  • Thử mẫu với nhiều tổ hợp biến có và không có
  • Dùng biểu thức điều kiện cho những phần tùy chọn

Giám sát

Hãy giám sát các tích hợp webhook của bạn để đảm bảo chúng hoạt động đúng:

  • Ghi log những lần gọi webhook thành công và thất bại trong ứng dụng của bạn
  • Theo dõi tỷ lệ gửi thông báo và thời gian phản hồi
  • Thiết lập cảnh báo cho lỗi webhook hoặc những mẫu hình bất thường
  • Định kỳ rà soát và thử lại những tích hợp webhook quan trọng

Quyền riêng tư và bảo mật

Hiểu cách Echobell xử lý dữ liệu webhook của bạn:

Những gì được lưu

  • Trên máy chủ của chúng tôi:

    • Webhook URL (token) - cần thiết để định tuyến request đến đúng kênh
    • Cấu hình kênh - mẫu, điều kiện, thiết lập
    • Quan hệ đăng ký - ai đăng ký kênh nào

  • Trên thiết bị của bạn:

    • Nội dung thông báo - phần tiêu đề và nội dung đã được kết xuất
    • Lịch sử kích hoạt - thời điểm nhận thông báo
    • Giá trị biến - dữ liệu truyền trong các lần gọi webhook
    • Liên kết và siêu dữ liệu - externalLink cùng các dữ liệu liên quan khác

Những gì không được lưu

  • Chúng tôi không lưu vĩnh viễn payload webhook thô
  • Chúng tôi không ghi log hay giữ lại dữ liệu nhạy cảm từ request của bạn
  • Chúng tôi không phân tích hay xử lý nội dung thông báo vì bất kỳ mục đích nào
  • Chúng tôi không chia sẻ dữ liệu webhook của bạn với bên thứ ba

Khuyến nghị bảo mật

  • Hãy coi webhook URL như API key - chúng cho phép gửi thông báo mà không cần xác thực
  • Đổi mới URL thường xuyên - dùng tính năng "Reset Token" để tạo URL mới
  • Dùng HTTPS client - chúng tôi chỉ chấp nhận kết nối HTTPS, nhưng hãy đảm bảo client của bạn có kiểm tra chứng chỉ
  • Kiểm soát nguồn gọi webhook - nếu có thể, hãy giới hạn những IP hoặc dịch vụ được phép gọi webhook của bạn
  • Theo dõi dấu hiệu lạm dụng - để ý những mẫu hình bất thường hoặc việc sử dụng trái phép
  • Tách biệt các môi trường - dùng kênh khác nhau cho phát triển, staging và production

Tìm hiểu thêm trong tài liệu hỗ trợ của chúng tôi.

Xử lý sự cố

Nếu webhook không hoạt động như mong đợi, hãy thử các bước chẩn đoán sau:

Webhook không kích hoạt thông báo

  1. Kiểm tra webhook URL có đúng không

    • Sao chép URL trực tiếp từ ứng dụng Echobell
    • Đảm bảo không có khoảng trắng hay ký tự thừa
    • Kiểm tra bạn đang dùng https://hook.echobell.one/t/ chứ không phải tên miền nào khác

  2. Kiểm tra kênh còn hoạt động không

    • Mở kênh trong ứng dụng Echobell
    • Xác nhận nó chưa bị xóa hay lưu trữ
    • Xác nhận bạn chưa đặt lại token webhook (việc đó sẽ làm URL cũ mất hiệu lực)

  3. Đảm bảo payload JSON của bạn đúng định dạng (với request POST)

    • Dùng công cụ kiểm tra JSON để soát lại payload
    • Đảm bảo chuỗi được đặt trong dấu nháy đúng cách
    • Kiểm tra header Content-Type đã được đặt là application/json

  4. Xác nhận mọi biến mà mẫu cần đều được cung cấp

    • Xem lại mẫu thông báo để biết chúng dùng những biến nào
    • Kiểm tra những biến đó có trong request webhook không (tham số query hoặc body JSON)
    • Hãy nhớ rằng biến bị thiếu sẽ được kết xuất thành chuỗi rỗng

  5. Kiểm tra kênh có người đăng ký đang hoạt động không

    • Thông báo chỉ được gửi nếu có người đăng ký kênh
    • Xác nhận lượt đăng ký của bạn trong danh sách kênh của ứng dụng
    • Kiểm tra xem các lượt đăng ký có bị gỡ nhầm không

Thông báo hiển thị sai

  1. Tên biến không khớp

    • Mẫu dùng {{server_name}} nhưng webhook lại gửi serverName
    • Tên biến phân biệt chữ hoa chữ thường và phải khớp chính xác
    • Kiểm tra lỗi gõ trong tên biến

  2. Không truy cập được dữ liệu lồng nhau

    • Dùng cú pháp dấu chấm: {{user.name}} hoặc cú pháp ngoặc vuông: {{user["name"]}}
    • Kiểm tra cấu trúc JSON của bạn có khớp với những gì mẫu mong đợi không
    • Hãy thử với biến phẳng đơn giản trước, rồi mới thêm cấu trúc lồng nhau

  3. Ký tự đặc biệt gây lỗi

    • Mã hóa URL cho tham số query một cách đúng đắn
    • Escape các ký tự đặc biệt của JSON trong body POST
    • Hãy thử với văn bản ASCII đơn giản trước

Kiểm thử tích hợp của bạn

Dùng curl để thử webhook trực tiếp:

# Thử với tham số query
curl "https://hook.echobell.one/t/<channel-token>?test=hello&status=working"

# Thử với body JSON
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H "Content-Type: application/json" \
  -d '{"test": "hello", "status": "working"}'

Bạn sẽ nhận được thông báo ngay lập tức nếu mọi thứ đã được cấu hình đúng.

Vẫn gặp vấn đề?

Nếu bạn đã thử các bước trên mà vẫn gặp trục trặc:

  • Ghé Trung tâm hỗ trợ để xem thêm các hướng dẫn xử lý sự cố
  • Kiểm tra xem có sự cố đã biết hoặc cập nhật trạng thái dịch vụ nào không
  • Liên hệ chúng tôi tại echobell@weelone.com kèm theo:
    • Mô tả vấn đề
    • Những bước bạn đã thử
    • Ví dụ webhook URL (đã xóa/che phần token)
    • Payload request mẫu
    • Kết quả mong đợi so với kết quả thực tế

Bước tiếp theo

Giờ bạn đã hiểu về tích hợp webhook:

Sẵn sàng tích hợp Echobell vào hệ thống của bạn chưa? Hãy tạo kênh đầu tiên và bắt đầu nhận thông báo tức thì!