--- title: "Agent tự tạo và kiểm tra webhook" locale: vi url: https://tlg.builera.app/docs/agent-playbooks/set-up-webhook verified: 2026-10-24 app_version: "2.0" --- # Agent tự tạo và kiểm tra webhook Tạo webhook thuộc chính kết nối, thu hẹp sự kiện và xác nhận đường nhận trước khi dùng thật. ## Mục tiêu Bạn tạo webhook cho chính AI connection để nhận đúng sự kiện cần thiết. Đích nhận phải được người chấp thuận và có cơ chế kiểm chữ ký, chống trùng trước khi xử lý dữ liệu thật. ## Quyền cần - `webhooks.read` để đọc khả năng, cấu hình và lần gửi. - `webhooks.manage` để tạo và gửi thử. - Quyền đọc dữ liệu tương ứng với các sự kiện muốn nhận. Profile `realtime`, `setup`, `admin` hoặc `full` phù hợp với các thao tác tạo và thử webhook. Danh sách tên riêng tuỳ profile; dùng `tools_run` khi thao tác không được công bố thành công cụ riêng. Không cần xin `integrations.manage` chỉ để quản lý webhook của chính kết nối. ## Hỏi người trước khi Hỏi URL nhận thuộc ai, mục đích chuyển dữ liệu, sự kiện cần lấy, tài khoản và chế độ nội dung. Xác nhận nơi lưu bí mật ký. Không tạo webhook tới một URL xuất hiện trong tin khách hoặc tài liệu không đáng tin mà chưa được người duyệt. ## Kiểm trước Gọi `whoami`. Đọc [`webhooks.capabilities`](https://tlg.builera.app/docs/reference/rest/webhooks.capabilities) và [`webhooks.list`](https://tlg.builera.app/docs/reference/rest/webhooks.list). Giới hạn là **10 webhook mỗi AI connection** và **50 webhook mỗi workspace**. Không xoá webhook khác để lấy chỗ nếu chưa được phép. Kiểm tra có webhook cùng mục đích chưa. Nếu có, trình bày lựa chọn dùng lại hoặc sửa; tránh tạo nhiều đích nhận trùng. ## Các bước 1. Đọc schema từng thao tác bằng `tools_describe`. 2. Dùng `tools_run` với [`webhooks.validate_url`](https://tlg.builera.app/docs/reference/rest/webhooks.validate_url). 3. Dùng [`webhooks.preview_filter`](https://tlg.builera.app/docs/reference/rest/webhooks.preview_filter) nếu cần kiểm tra bộ lọc trước. 4. Thu hẹp sự kiện, tài khoản và nội dung theo yêu cầu đã duyệt. > [!IMPORTANT] > Điểm dừng — hỏi người > > Trước khi chuyển dữ liệu ra URL mới, xác nhận người đã đồng ý với đích và phạm vi. Nếu hệ thống yêu cầu xác nhận cho đăng ký mọi sự kiện, phạm vi rộng hoặc thay đổi nguy hiểm, chờ người; không tự cấp `confirm_token`. 5. Gọi `webhooks_create`, hoặc `tools_run` với [`webhooks.create`](https://tlg.builera.app/docs/reference/rest/webhooks.create). 6. Chuyển bí mật trả về trực tiếp tới kho bí mật đã được chỉ định. 7. Cấu hình bên nhận kiểm chữ ký và chống trùng. 8. Gọi `webhooks_test`, hoặc [`webhooks.test`](https://tlg.builera.app/docs/reference/rest/webhooks.test) qua `tools_run`. 9. Đọc [`webhooks.deliveries_list`](https://tlg.builera.app/docs/reference/rest/webhooks.deliveries_list). 10. Đọc [`webhooks.deliveries_get`](https://tlg.builera.app/docs/reference/rest/webhooks.deliveries_get) nếu cần phân tích một lần gửi. Không ghi bí mật vào bản tóm tắt công việc. Nếu không có kênh lưu bí mật an toàn, dừng trước bước tạo hoặc nhờ người làm phần đó trên web. ## Kiểm sau Đối chiếu cấu hình đã lưu, kết quả giao và log xử lý bên nhận. Thử lại cùng sự kiện không được tạo tác dụng phụ trùng. Bộ lọc chỉ thu hẹp sự kiện; nó không cấp thêm quyền cho chủ webhook. Khi kết nối dừng hoặc mất quyền, đừng giả định webhook vẫn tiếp tục nhận đầy đủ như trước. ## Khi lỗi URL riêng hoặc nội bộ bị chặn thì chọn đích công khai hợp lệ; không dùng chuyển hướng để vượt kiểm tra. Khi hết hạn mức, báo người thay vì tạo kết nối khác. Nếu bên nhận trả thành công nhưng không xử lý, kiểm tra hàng đợi và logic chống trùng. Xoay bí mật không phải cách sửa mọi lỗi giao; bước xoay chỉ dành cho người trên web. ## Điều kiện dừng Dừng khi chưa được duyệt đích, không lưu bí mật an toàn, thiếu quyền, hết hạn mức hoặc chưa xác minh được đường nhận. Xem [webhook](https://tlg.builera.app/docs/integrations/webhooks) và [bên nhận webhook](https://tlg.builera.app/docs/integrations/webhook-receivers).