Tài liệu

Tích hợp

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.

Xem Markdown

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
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.

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, webhooks.test, webhooks.deliveries_list, webhooks.redeliver và 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.