Thông báo Direct - Khóa API cá nhân cho cảnh báo tức thì

Thông báo Direct cho phép bạn gửi cảnh báo cá nhân qua một webhook URL đơn giản — không cần lập kênh, không cần mẫu, không cần người đăng ký. Chỉ cần tạo một khóa, gọi URL đó và nhận thông báo ngay trên thiết bị của bạn.

Direct là gì?

Kênh rất phù hợp cho những thông báo có cấu trúc, dùng mẫu và có thể chia sẻ với người khác. Nhưng đôi khi bạn chỉ muốn một thông báo nhanh, cho riêng mình — bản dựng đã xong, script đã chạy hết, một cảm biến vừa được kích hoạt. Direct sinh ra đúng cho việc đó.

Với Direct, bạn có một khóa API cá nhân tương ứng với một webhook URL riêng. Khi bạn gọi URL đó kèm tiêu đề và nội dung, một thông báo sẽ được gửi thẳng tới bạn. Không cần cấu hình kênh nào cả.

Khi nào dùng Direct thay vì kênh

	Direct	Kênh
Thiết lập	Tạo một khóa, dùng URL	Tạo kênh, cấu hình mẫu
Người nhận	Chỉ mình bạn	Bất kỳ ai đăng ký
Mẫu	Không có — bạn tự đặt tiêu đề/nội dung cho mỗi request	Mẫu cấu hình được kèm biến
Điều kiện	Không có	Có hỗ trợ gửi theo điều kiện
Phù hợp nhất cho	Script cá nhân, cảnh báo nhanh, tự động hóa	Cảnh báo chia sẻ, quy trình có cấu trúc

Bắt đầu

1. Tạo một khóa Direct

Trong ứng dụng Echobell, nhấn Direct ở đầu danh sách kênh của bạn. Sau đó nhấn Tạo (Create) để sinh một khóa Direct mới. Hãy đặt cho nó một cái tên mô tả (ví dụ: "Build Server", "Home Lab", "Trading Bot").

2. Sao chép webhook URL

Mỗi khóa Direct có một webhook URL riêng theo định dạng sau:

https://hook.echobell.one/d/{your-key-token}

Bạn có thể tìm và sao chép URL này trong phần chi tiết của khóa Direct trong ứng dụng. Token được ẩn mặc định vì lý do bảo mật — hãy nhấn vào để hiện.

3. Gửi một thông báo

Gọi webhook URL với một JSON body chứa title và body:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Build Complete",
  "body": "Project X built successfully in 3m 42s"
}

Chỉ vậy thôi — bạn sẽ nhận được thông báo ngay lập tức.

Cách gửi request

Request POST (khuyến nghị)

Gửi một JSON body chứa nội dung thông báo của bạn:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Deployment Status",
  "body": "v2.1.0 deployed to production",
  "externalLink": "https://dashboard.example.com/deploys/latest"
}

Request GET

Bạn cũng có thể truyền tham số qua chuỗi truy vấn:

GET https://hook.echobell.one/d/YOUR_KEY_TOKEN?title=Alert&body=CPU+at+95%25

Chỉ POST

Mỗi khóa Direct có thiết lập Chỉ POST (POST Only) riêng trong ứng dụng Echobell. Mặc định thiết lập này tắt.

Khi bật, chỉ POST mới kích hoạt được khóa đó. Một request GET tới webhook URL của nó sẽ bị từ chối với 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ù Chỉ POST đang bật hay tắt.

Thiết lập này áp dụng riêng cho từng khóa, nên bạn có thể giữ một khóa hỗ trợ GET cho các lệnh shell một dòng, và một khóa chỉ POST cho những URL bị dán vào phòng chat hay trang wiki.

Các trường trong request

Mọi tên trường đều không phân biệt chữ hoa chữ thường — title, Title và TITLE đều được xử lý như nhau, dù truyền qua JSON body hay chuỗi truy vấn.

Trường	Kiểu	Bắt buộc	Mô tả
`title`	string	Không	Tiêu đề thông báo. Mặc định là "Direct Notification" nếu bỏ trống.
`body`	string	Không	Nội dung văn bản của thông báo.
`externalLink`	string	Không	Một liên kết bấm được hiển thị trong bản ghi thông báo.
`notificationType`	string	Không	Mức độ khẩn của thông báo. Nhận `active`, `time-sensitive` hoặc `calling`. Mặc định là `active`. Xem Kiểu thông báo.

Kiểu thông báo

Bạn có thể điều chỉnh mức độ khẩn của thông báo Direct bằng trường notificationType:

Kiểu	Mô tả
`active`	Thông báo thông thường, gửi theo cách thông thường. Đây là giá trị mặc định.
`time-sensitive`	Thông báo ưu tiên cao, có thể vượt qua chế độ Tập trung.
`calling`	Cảnh báo dạng cuộc gọi cho tình huống nguy cấp. Yêu cầu gói premium đang hoạt động. Nếu không có premium, sẽ tự chuyển về `time-sensitive`.

Ví dụ có kèm kiểu thông báo:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Server Down",
  "body": "Production server is unresponsive",
  "notificationType": "calling"
}

Định dạng phản hồi

Một request thành công trả về:

{
  "success": true,
  "message": "Notification triggered successfully."
}

Nếu khóa không hợp lệ hoặc không tìm thấy (lưu ý là vẫn trả về HTTP 200):

{
  "success": false,
  "message": "Direct key not found."
}

Quản lý khóa Direct

Nhiều khóa

Bạn có thể tạo nhiều khóa Direct cho các mục đích khác nhau:

"CI Server" — cho thông báo về bản dựng và triển khai
"Home Automation" — cho cảnh báo từ cảm biến IoT
"Cron Jobs" — cho kết quả của tác vụ theo lịch
"Trading Bot" — cho cảnh báo thị trường

Mỗi khóa có webhook URL độc lập riêng. Bản ghi thông báo được tự động gắn với khóa đã kích hoạt chúng, nên bạn dễ dàng nhận ra dịch vụ nào đã gửi thông báo nào.

Đặt lại token

Nếu webhook URL của một khóa bị lộ, bạn có thể đặt lại token trong phần chi tiết của khóa đó. Thao tác này sinh ra một URL mới và vô hiệu hóa URL cũ ngay lập tức. Hãy cập nhật mọi script hoặc dịch vụ đang dùng URL cũ.

Xóa một khóa

Xóa một khóa Direct sẽ vô hiệu hóa vĩnh viễn webhook URL của nó. Mọi request tới URL cũ đều sẽ thất bại.

Trường hợp sử dụng phổ biến

Script shell

# Notify when a long-running task finishes
./run-migration.sh && \
curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Migration Complete", "body": "Database migration finished successfully"}'

Cron job

# In crontab: notify on backup completion
0 2 * * * /usr/local/bin/backup.sh && curl -s -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN -H "Content-Type: application/json" -d '{"title": "Backup Done", "body": "Nightly backup completed"}'

Python

import requests

requests.post(
    "https://hook.echobell.one/d/YOUR_KEY_TOKEN",
    json={
        "title": "Training Complete",
        "body": f"Model accuracy: {accuracy:.2%}",
        "externalLink": "https://wandb.ai/runs/abc123"
    }
)

Node.js

await fetch("https://hook.echobell.one/d/YOUR_KEY_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Deploy Complete",
    body: `Version ${version} deployed to production`,
  }),
});

GitHub Actions

- name: Notify via Echobell Direct
  if: always()
  env:
    ECHOBELL_DIRECT_URL: ${{ secrets.ECHOBELL_DIRECT_URL }}
  run: |
    curl -X POST "$ECHOBELL_DIRECT_URL" \
      -H "Content-Type: application/json" \
      -d '{"title": "Build ${{ job.status }}", "body": "${{ github.repository }} @ ${{ github.sha }}"}'

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

Bảo mật

Hãy coi URL của khóa Direct như thông tin bí mật — bất kỳ ai có URL đều gửi được thông báo cho bạn
Dùng biến môi trường để lưu token khóa trong script và CI/CD
Đặt lại token ngay khi bạn nghi ngờ một khóa đã bị lộ
Tạo các khóa riêng biệt cho từng dịch vụ để có thể thu hồi từng cái một

Cách tổ chức

Đặt tên khóa có tính mô tả — bạn sẽ cảm ơn chính mình khi phải quản lý nhiều khóa
Mỗi dịch vụ một khóa — giúp dễ nhận ra nguồn thông báo và dễ thu hồi quyền
Xóa các khóa không dùng — giảm bề mặt tấn công

Xử lý lỗi

Khi tích hợp Direct vào script của bạn, hãy rẽ nhánh dựa trên trường success trong JSON thay vì dựa vào mã trạng thái HTTP:

200 OK: Request đã được tiếp nhận. Hãy xem JSON body: success: true nghĩa là thông báo đã được kích hoạt; success: false nghĩa là không. Một khóa Direct không tồn tại hoặc đã bị đặt lại vẫn trả về HTTP 200 kèm { "success": false, "message": "Direct key not found." } — chứ không phải 404.
400 Bad Request: Token của khóa sai độ dài. Hãy sửa lại URL.
405 Method Not Allowed: Khóa đang bật Chỉ POST mà request lại không phải POST. Hãy chuyển bên gọi sang POST, hoặc tắt thiết lập đó đi.

Echobell không giới hạn tần suất gọi Direct, nên không có phản hồi 429.

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

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

Trên máy chủ của chúng tôi:
- Siêu dữ liệu của khóa Direct (tên, token đã băm, chủ sở hữu)
- Payload của request được xử lý và lưu tạm thời để phục vụ việc gửi đi
Trên thiết bị của bạn:
- Nội dung thông báo (tiêu đề, nội dung)
- Lịch sử kích hoạt và dấu thời gian
- Liên kết bên ngoài

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

Chúng tôi không giữ lại vĩnh viễn payload của request sau khi đã gửi thông báo
Chúng tôi không phân tích nội dung thông báo
Chúng tôi không chia sẻ dữ liệu của bạn với bên thứ ba

Khắc phục sự cố

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

Kiểm tra webhook URL — hãy sao chép trực tiếp từ ứng dụng, để ý khoảng trắng thừa
Kiểm tra khóa còn tồn tại không — có thể nó đã bị xóa hoặc token đã bị đặt lại
Đảm bảo đã cấp quyền thông báo — ứng dụng Echobell cần quyền gửi thông báo trên thiết bị của bạn

Thử bằng curl — để loại trừ lỗi từ HTTP client của bạn:

curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Test", "body": "Hello from Direct"}'

Lỗi request

Lỗi phân tích JSON: Đảm bảo đã đặt header Content-Type: application/json và body là JSON hợp lệ
Không tìm thấy khóa: Body có "success": false kèm "Direct key not found." nghĩa là token đã bị đặt lại hoặc khóa đã bị xóa (mã trạng thái HTTP vẫn là 200)

Vẫn gặp sự cố?

Ghé Trung tâm hỗ trợ để được trợ giúp thêm
Liên hệ chúng tôi tại echobell@weelone.com kèm:
- Mô tả vấn đề
- Ví dụ request (đã che token)
- Kết quả mong đợi so với thực tế

Bước tiếp theo

Tích hợp Webhook — Cho thông báo dùng chung, có mẫu, theo kênh
Cú pháp mẫu — Tìm hiểu về mẫu thông báo của kênh
Kích hoạt qua Email — Kích hoạt thông báo bằng email
Khám phá tích hợp — Kết nối với những công cụ bạn đang dùng