--- title: "Tạo và theo dõi webhook" locale: vi url: https://tlg.builera.app/docs/integrations/webhooks verified: 2026-10-24 app_version: "2.0" --- # Tạo và theo dõi webhook Gửi sự kiện có chữ ký tới hệ thống của bạn, theo dõi lần gửi và xử lý hàng lỗi. Bạn tạo webhook để hệ thống ngoài nhận sự kiện mà không phải liên tục hỏi API. Webhook gửi thông báo; muốn trả lời khách, bên nhận phải gọi thao tác gửi tin riêng. ## Ai làm được Trên web, bạn cần quyền quản lý tích hợp. AI connection có `webhooks.read` và `webhooks.manage` quản lý webhook của chính nó; `integrations.manage` mở phạm vi tới các webhook trong workspace. ## Cần chuẩn bị - URL nhận HTTPS công khai, chẳng hạn `https://example.com/telegram-events`. - Bên nhận biết kiểm chữ ký và chống xử lý trùng. - Danh sách sự kiện, tài khoản và nội dung thực sự cần chuyển ra ngoài. Giới hạn là **10 webhook cho mỗi AI connection**, **50 webhook cho cả workspace**. ## Bắt đầu ở đâu Mở **Cài đặt → Webhook**. ![Danh sách webhook và tình trạng gửi sự kiện](https://tlg.builera.app/docs-media/vi/settings-webhooks.webp "Webhook") ## Các bước 1. Mở biểu mẫu tạo webhook. 2. Nhập tên để phân biệt đích nhận. 3. Nhập URL nhận. 4. Chọn các sự kiện cần theo dõi. 5. Thu hẹp tài khoản nhận sự kiện. 6. Đặt bộ lọc theo nhu cầu. 7. Chọn chế độ nội dung. 8. Lưu cấu hình. 9. Lưu bí mật ký vào nơi giữ bí mật của bên nhận. 10. Mở webhook và chọn **Gửi thử**. Bộ lọc có thể thu hẹp theo loại chat, chiều tin, người gửi tự động, hội thoại hoặc từ khoá. Bộ lọc không mở rộng quyền của chủ webhook. | Chế độ | Cách dùng | |---|---| | `thin` | Nhận thông tin gọn, dùng API đọc thêm khi cần | | `full` | Nhận nội dung đầy đủ trong phạm vi quyền | | `none` | Không lấy phần nội dung mà bộ dựng payload loại bỏ ở chế độ này | Đừng hiểu `full` là quyền xem mọi trường. Dữ liệu vẫn bị giới hạn theo quyền; payload quá lớn có thể được rút gọn. ## Kết quả Bên nhận được POST với phong bì CloudEvents và chữ ký Standard Webhooks. Bạn xem kết quả ở **Lần gửi**, gồm trạng thái và lỗi từng lần thử. Một lần giao có tối đa **6 lần thử tổng cộng**, không phải sáu lần thử lại. Lịch là gửi ngay, rồi chờ **1 phút, 5 phút, 30 phút, 2 giờ, 6 giờ** sau lần thất bại trước. Lịch có độ lệch **±15%**; `Retry-After` hợp lệ có thể thay thời gian chờ, tối đa **6 giờ**. Webhook tự tắt khi có **20 lỗi liên tiếp và thời gian lỗi kéo dài ít nhất 1 giờ**, hoặc mọi lần đều lỗi suốt **12 giờ**. Phản hồi `410` cũng làm webhook ngừng. ## Kiểm tra Mở **Hàng lỗi & Phát lại** để xem DLQ. Sửa bên nhận trước khi gửi lại lần giao lỗi hoặc phát lại sự kiện theo khoảng cần thiết. Phát lại có thể tạo tác dụng phụ trùng nếu bên nhận chưa chống trùng theo ID sự kiện. Trong **Cài đặt & Bí mật**, người vận hành có thể chọn **Xoay bí mật**. Giữ bên nhận chấp nhận cả khoá cũ và mới trong thời gian chuyển tiếp. Mọi ảnh chụp phải che kín bí mật. > [!WARNING] > Xoá webhook ngừng gửi ngay và xoá hàng chờ, lịch sử gửi. Không hoàn tác được. ## Khi có lỗi URL phải là HTTPS công khai. Hệ thống chặn địa chỉ riêng, loopback, đích nội bộ và đích quay về ứng dụng; kiểm tra DNS được thực hiện ở phía máy chủ. Không dùng chuyển hướng để né kiểm tra URL. ## Làm bằng API hoặc MCP Dùng [webhooks.create](https://tlg.builera.app/docs/reference/rest/webhooks.create), [webhooks.test](https://tlg.builera.app/docs/reference/rest/webhooks.test), [webhooks.deliveries_list](https://tlg.builera.app/docs/reference/rest/webhooks.deliveries_list), [webhooks.redeliver](https://tlg.builera.app/docs/reference/rest/webhooks.redeliver) và [webhooks.replay](https://tlg.builera.app/docs/reference/rest/webhooks.replay). MCP có `webhooks_create`, `webhooks_test` trên profile công bố chúng; thao tác còn lại gọi qua `tools_run`. Đổi bí mật chỉ dành cho người trên web. Xem [kiểm chữ ký bên nhận](https://tlg.builera.app/docs/integrations/webhook-receivers).