# Cảnh báo qua Telegram, Slack, email và webhook

> Mỗi workspace tự kết nối bot Telegram, Slack webhook, email (SMTP/Resend) hoặc webhook HTTPS của mình, rồi đặt quy tắc gửi.

Cảnh báo báo cho đội của bạn biết khi có issue mới, lỗi tái phát và lỗi tăng vọt. **Mỗi workspace tự kết nối kênh gửi của mình** — bot Telegram, Slack webhook, tài khoản email, hoặc địa chỉ HTTPS của chính bạn. Belvador không có kênh gửi mặc định dùng chung, nên tin được gửi dưới tên của bạn và theo giới hạn của nhà cung cấp bạn dùng.

Cảnh báo nằm ở mục **Cảnh báo** trong workspace. Owner và admin quản lý; thêm, sửa hoặc xoá một đích nhận sẽ hỏi mã xác thực.

## 1. Thêm đích nhận

**Đích nhận** là nơi cảnh báo được gửi tới. Chọn **Thêm đích nhận**, đặt tên, chọn các project được gửi tới đích này, rồi chọn một trong các loại:

### Telegram

1. Trong Telegram mở **@BotFather**, gửi `/newbot` và làm theo hướng dẫn. Sao chép token nó trả về.
2. Dán vào ô **Token của bot** (dạng `123456789:AA…`) và chọn **Kiểm tra bot**. Belvador hiện **Đã tìm thấy bot: @botcuaban**.
3. Chỉ cho bot nơi nhận cảnh báo:
   - **Mở Telegram** (hoặc quét mã QR bằng điện thoại) để bắt đầu chat riêng với bot, hoặc
   - **Thêm vào nhóm**, rồi trong nhóm gửi tin nhắn mà Belvador hiển thị.
4. Belvador chờ tin nhắn đó và hiện cuộc trò chuyện tìm được — chat riêng, nhóm hoặc kênh.
5. Với kênh, hoặc bot đang dùng webhook, chọn **Nhập chat ID thay vào đó**. ID của nhóm và kênh bắt đầu bằng `-100`.

Trước khi lưu, Belvador gửi một tin “đã kết nối” vào cuộc trò chuyện đó. Token của bot được lưu mã hoá và chỉ dùng để gửi cảnh báo.

### Slack

1. Trong Slack: **Apps → Incoming Webhooks → Add to Slack**, chọn kênh và sao chép webhook URL.
2. Dán vào ô **Webhook URL** — bắt đầu bằng `https://hooks.slack.com/services/`.

Belvador gửi một tin xác nhận vào kênh trước khi lưu.

### Email

Chọn cách gửi:

| Gửi bằng | Bạn nhập |
|---|---|
| **Tài khoản SMTP** | Nhà cung cấp (mẫu sẵn cho các nhà cung cấp phổ biến, hoặc **Nhà cung cấp khác**), **Máy chủ SMTP**, **Cổng** — 465 cho TLS, 587 cho STARTTLS — **Tên đăng nhập** và **Mật khẩu** |
| **Resend** | Một **Khoá API Resend** có quyền “Sending access” |

Sau đó nhập địa chỉ **Người gửi** (có thể thêm tên hiển thị phía trước) và tối đa 10 **Địa chỉ** nhận.

- Với SMTP, dùng **mật khẩu ứng dụng**, không dùng mật khẩu thường; tài khoản cần bật xác minh 2 bước. Belvador không bao giờ gửi mật khẩu khi chưa mã hoá.
- Với Resend, địa chỉ người gửi phải thuộc tên miền đã xác minh trong Resend.
- Microsoft 365: quản trị viên phải bật đăng nhập SMTP cho hộp thư. Tài khoản Outlook.com chỉ cho đăng nhập bằng tài khoản Microsoft, hiện chưa hỗ trợ.

Belvador gửi trước một email thử tới bạn; đích nhận chỉ được lưu khi máy chủ email nhận thư đó. Sau đó mỗi người nhận sẽ có một email xác nhận và phải chọn **Xác nhận địa chỉ này** trước khi nhận cảnh báo — địa chỉ đăng nhập của bạn được xác nhận sẵn. Mỗi email cảnh báo đều có liên kết **Ngừng nhận email này**.

Đích nhận hiện số email đã gửi hôm nay và cảnh báo khi bạn sắp chạm giới hạn mỗi ngày của nhà cung cấp.

### Webhook

Dán **URL nhận** HTTPS của hệ thống bạn. Belvador gửi trước một sự kiện thử có chữ ký và chỉ lưu khi nhận `2xx`, rồi hiện mã ký một lần. Mọi cảnh báo tới dưới dạng JSON có chữ ký theo chuẩn Standard Webhooks — xem [Webhook tự cấu hình](https://belvador.dev/vi/docs/alerts/webhooks) để có code kiểm chữ ký, loại sự kiện và cách thử lại.

### PagerDuty và incident.io

Để gọi người trực, kết nối công cụ trực thay vì kênh chat:

- **PagerDuty** — trong PagerDuty mở **Service → Integrations → Events API v2** và chép **Integration key** (32 ký tự); chọn vùng của tài khoản (US hoặc EU).
- **incident.io** — trong incident.io mở **Alerts → Sources → HTTP**, tạo một source rồi chép **Alert source ID** (26 ký tự) và **Source token**.

Belvador gửi một cảnh báo thử và đóng nó ngay trước khi lưu. Các đích này nhận [sự cố](https://belvador.dev/vi/docs/incidents) mỗi sự cố một trang — mở, đã nhận (PagerDuty), đã xong — thay vì mỗi cảnh báo một trang, và không bao giờ bị giữ bởi giờ yên tĩnh.

## 2. Tạo quy tắc

**Quy tắc** quyết định lỗi nào đáng báo. Chọn **Quy tắc mới**:

| Mục | Lựa chọn |
|---|---|
| **Cảnh báo khi** | **Lỗi**, **Sự cố kết nối**, **Sự cố monitor**, **Kiểm tra uptime** hoặc **SLO** (xem bên dưới) |
| **Khi nào** | **Issue mới**, **Quay lại** (issue đã xử lý xuất hiện lại), **Tăng vọt** (lỗi tăng đột ngột) |
| **Project** | Mọi project, hoặc các project bạn chọn |
| **Level tối thiểu** | **Warning trở lên**, **Error trở lên**, **Chỉ fatal** |
| **Môi trường** | Cách nhau bằng dấu phẩy, ví dụ `production`. Trống = mọi môi trường |
| **Không lặp lại trong** | Số phút trước khi cùng một issue được báo lại |
| **Đích nhận** | Một hoặc nhiều đích nhận ở bước 1 |

Khi lưu sẽ có bước xác nhận.

## Cảnh báo sự cố kết nối

Mỗi workspace còn có sẵn quy tắc mặc định **Sự cố kết nối SDK**. Quy tắc gửi một tin khi Belvador mở một [sự cố kết nối](https://belvador.dev/vi/docs/sdk/verify#ma-su-co-ket-noi) cho project — khoá đã thu hồi vẫn được dùng, lỗi từ tên miền bị chặn, lỗi bị bỏ vì giới hạn, code máy chủ nằm ngoài middleware của Belvador — và một tin **Kết nối ổn lại** khi sự cố đóng. Sự cố quay lại trong vòng 6 giờ được mở lại lặng lẽ, không báo thêm. Tin chỉ ghi project, sự cố và liên kết tới tab **Kết nối**; không bao giờ chứa nội dung lỗi, địa chỉ trang hay khoá.

Để thêm một quy tắc tương tự, chọn **Quy tắc mới → Cảnh báo khi → Sự cố kết nối**. Level tối thiểu, môi trường và **Không lặp lại trong** không áp dụng. Tắt quy tắc sẽ dừng tin; tab Kết nối vẫn hiện mọi sự cố.

## Cảnh báo monitor

Quy tắc mặc định **Sự cố monitor** gửi một tin khi một [monitor](https://belvador.dev/vi/docs/monitors/overview) — kể cả [monitor ping URL](https://belvador.dev/vi/docs/monitors/heartbeat) — bắt đầu hỏng — lượt bị lỡ, lượt lỗi, lượt quá thời gian chạy tối đa, hoặc kết quả cần xem lại — và một tin **Đã ổn lại** khi khoẻ trở lại. Đổi từ loại hỏng này sang loại khác không gửi tin mới. Tin ghi monitor, project, môi trường, lịch và lượt khoẻ gần nhất, kèm liên kết tới monitor; không bao giờ chứa nội dung lỗi, khoá, ID người dùng hay trace ID. Nếu node mất kết nối trong lúc có sự cố, tin ghi rõ là phát hiện trễ.

Để thu hẹp, chọn **Quy tắc mới → Cảnh báo khi → Sự cố monitor** rồi chọn loại sự cố, project, môi trường và **Không lặp lại trong**. Monitor đã tắt tiếng không gửi gì, bất kể quy tắc; sự cố vẫn hiện trên trang.

## Cảnh báo uptime

Quy tắc mặc định **Sự cố uptime** gửi một tin khi một [kiểm tra uptime](https://belvador.dev/vi/docs/uptime/quickstart) bị lỗi — hỏng từ đa số vùng — và một tin **Hoạt động lại** khi truy cập được trở lại, cộng tối đa một cảnh báo mỗi ngày khi chứng chỉ HTTPS sắp hết hạn. Tin ghi tên kiểm tra, project, môi trường, địa chỉ đích đã bỏ phần query, lý do hỏng và các vùng đang hỏng; không bao giờ chứa nội dung hay header của phản hồi.

Để thu hẹp, chọn **Quy tắc mới → Cảnh báo khi → Kiểm tra uptime** rồi chọn project, môi trường và **Không lặp lại trong**. Kiểm tra đã tắt tiếng vẫn kiểm và ghi lại nhưng không gửi gì.

## Cảnh báo SLO

Quy tắc mặc định **SLO đang đốt** gửi một tin khi một [SLO](https://belvador.dev/vi/docs/slos) bắt đầu đốt ngân sách lỗi quá nhanh — đốt nhanh thì gọi khẩn, đốt chậm thì mở ticket — và một tin khi trở lại trong ngân sách. SLO thiếu dữ liệu không gửi gì thay vì đoán.

Để thu hẹp, chọn **Quy tắc mới → Cảnh báo khi → SLO** rồi chọn mức độ, project, môi trường và **Không lặp lại trong**. SLO đang tạm dừng hoặc tắt tiếng không gửi gì. Ngưỡng và cửa sổ: [Cảnh báo tốc độ đốt](https://belvador.dev/vi/docs/slos/alerts).

## Trạng thái và lịch sử

Mỗi đích nhận hiện **Đang chờ**, **Hoạt động**, **Đang lỗi** hoặc **Đã tắt**. **Đang lỗi** nghĩa là nhà cung cấp từ chối các tin gần đây — token bot bị thu hồi, webhook bị xoá, mật khẩu email đã đổi. Cập nhật đích nhận để sửa; **Lần gửi** trên đích nhận liệt kê từng lần thử kèm mã HTTP, thời gian và phản hồi của nhà cung cấp.

Lịch sử gửi liệt kê thời gian, event, đích nhận và trạng thái:

| Trạng thái | Ý nghĩa |
|---|---|
| **Đã gửi** | Nhà cung cấp đã nhận (HTTP 2xx hoặc máy chủ mail trả OK). Không có nghĩa là đã có người đọc |
| **Đang chờ** | Đang chờ gửi |
| **Chặn lặp** | Bỏ qua vì cùng issue vừa được báo (**Không lặp lại trong**) |
| **Đang thử lại** | Nhà cung cấp lỗi; Belvador thử lại |
| **Lỗi** | Đã dừng sau khi thử lại, hoặc nơi nhận từ chối hẳn. Owner và admin có thể **Gửi lại** trong vòng 7 ngày |
| **Đang giữ** | Chờ hết giờ yên tĩnh hoặc chờ bản tóm tắt kế tiếp ([chính sách thông báo](https://belvador.dev/vi/docs/alerts/policies)) |
| **Đã vào tóm tắt** | Đã gửi thành một dòng trong tin tóm tắt |

Nhãn **trễ** nghĩa là tin được gửi muộn hơn bình thường, ví dụ sau khi node kết nối lại.

Các cảnh báo liên quan có thể gom thành một [sự cố](https://belvador.dev/vi/docs/incidents) với mỗi đích một tin, và [chính sách thông báo](https://belvador.dev/vi/docs/alerts/policies) thêm giờ yên tĩnh, bản tóm tắt, chuỗi dự phòng khi một đích liên tục lỗi và leo thang khi chưa ai nhận sự cố.