Webhook gửi cập nhật vào kênh

Phạm vi hiện tại: chức năng quản lý và nhận webhook được tắt mặc định; chỉ dùng khi môi trường/tổ chức đã được bật. Mở ở đâu: khu quản trị webhook tại /settings/organization/webhooks hoặc liên kết quản lý từ đầu kênh. Quyền: chủ/quản trị và có quyền truy cập kênh đích.

Webhook là đường cho một hệ thống bên ngoài đăng cập nhật vào kênh đã chọn. Nó khác Nguồn kết nối và không tự trao quyền điều khiển trợ lý.

Tạo nguồn

Chọn Tạo webhook.
Điền Tên nguồn, chọn Kênh và Chủ đề mặc định.
Kiểm tra đích rồi tạo. Kênh đích không đổi được về sau; chọn đúng ngay từ đầu.
Sao chép URL webhook ngay vào nơi giữ bí mật của hệ thống gửi. URL chỉ hiện ở bước cấp khóa và bị che khi đóng, chuyển nền hoặc đổi tài khoản/tổ chức.

Ai có URL còn hiệu lực có thể gửi theo phạm vi nguồn. Không dán URL vào tài liệu chung, ảnh báo lỗi hoặc mã nguồn công khai. Nếu mất khóa, dùng chức năng đổi khóa; không cố tìm lại qua lịch sử trình duyệt của người khác.

Gửi thử và kiểm tra

Mở nguồn → Gửi thử, nhập nội dung và ảnh được phép rồi xác nhận. Đây là tin nhắn thật trong kênh và có thể thông báo tới thành viên, nên dùng kênh thử riêng.

Mở Lịch sử gửi, kiểm tra trạng thái rồi Xem tin nhắn. Đã đăng, Đã chuyển gửi thông báo và thiết bị thực nhận là các kết quả riêng. Nội dung chứa @lumi hoặc @channel từ hệ thống ngoài không tự được quyền kích hoạt AI/nhắc cả kênh.

Giới hạn của luồng này: nội dung tối đa 4.000 ký tự Unicode; ảnh JPEG, PNG hoặc WebP tĩnh, tối đa 10 ảnh, 10 MiB mỗi ảnh và 25 MiB tổng. Hệ thống gửi cần tuân theo định dạng ở phần tiếp theo và dùng khóa chống gửi trùng cho cùng sự kiện.

Gửi từ hệ thống bên ngoài

Phần này dành cho người cấu hình tích hợp. Chuẩn bị một webhook vào kênh thử được phép đăng, đặt URL bí mật vừa được cấp vào biến môi trường LUMI_WEBHOOK_URL bằng công cụ giữ bí mật của bạn. Ví dụ không chứa URL hay khóa thật; chỉ chạy sau khi đã kiểm tra đích và được phép gửi thử.

Yêu cầu văn bản dùng HTTP POST, Content-Type: application/json, content bắt buộc với JSON chỉ chứa văn bản; topic là tùy chọn. Chỉ luồng có ảnh mới cho phép bỏ content. Nếu bỏ topic, hệ thống dùng chủ đề mặc định; không gửi chủ đề rỗng. Gửi Idempotency-Key riêng cho mỗi sự kiện; khi thử lại chính sự kiện đó, giữ nguyên khóa và nội dung.

curl --fail-with-body --include --request POST "$LUMI_WEBHOOK_URL" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: lumi-guide-test-20260913-01' \
  --data '{"content":"TEST — Đã kiểm tra vật tư; chưa xác nhận ngày giao.","topic":"Kiểm thử tích hợp"}'

Gửi lại nguyên yêu cầu phải không sinh tin thứ hai. Đổi nội dung cho cùng khóa có thể bị báo xung đột; dùng khóa mới cho sự kiện mới. Mặc định thành công trả 204 No Content. Nếu URL có tham số wait=true, phản hồi thành công 200 có mã lần gửi/tin nhắn và trạng thái; vẫn kiểm tra tin ở kênh.

Với ảnh, dùng multipart/form-data: một trường chuỗi payload_json chứa JSON như trên và các tệp files[0], files[1] theo thứ tự liên tục. Chuẩn bị tệp ảnh thử anh-thu.png trước khi dùng ví dụ sau; để curl tự tạo phần biên của multipart.

curl --fail-with-body --include --request POST "$LUMI_WEBHOOK_URL" \
  --header 'Idempotency-Key: lumi-guide-test-20260913-02' \
  --form 'payload_json={"content":"TEST — Ảnh vật tư đã kiểm tra."}' \
  --form 'files[0]=@./anh-thu.png;type=image/png'

Không truyền organization_id, channel_id, người gửi giả, URL ảnh từ xa hoặc danh sách người được nhắc; đích và quyền đã cố định trong webhook. Khi lỗi, đọc mã phản hồi: dữ liệu không hợp lệ cần sửa dữ liệu, khóa/nguồn không hợp lệ cần kiểm tra cấu hình, quá giới hạn cần giảm yêu cầu hoặc đợi theo hướng dẫn. Không đổi khóa chống trùng chỉ để lặp một lần gửi mà chưa biết đã được ghi hay chưa.

Đổi khóa, tắt hoặc xóa

Đổi khóa làm URL cũ không còn hiệu lực; cập nhật hệ thống gửi. Tắt dừng nhận bài mới. Xóa webhook không xóa những tin đã đăng; sau xóa, nguồn rời danh sách và lịch sử chi tiết của nguồn không còn mở được tại đó. Kiểm tra nguồn đã biến mất và tin cũ còn trong kênh; với đổi khóa/tắt, kiểm tra trạng thái và lần gửi thử phù hợp.

Kiểm thử phân hệ

Gửi một sự kiện thử với cùng khóa chống trùng hai lần; cần chỉ có một tin. Tắt nguồn hoặc đổi khóa rồi thử URL cũ theo kế hoạch: không được đăng mới; tin lịch sử vẫn còn. Thử ảnh vượt giới hạn và người không có quyền quản lý. Nếu chức năng chưa bật, ghi Bị chặn thay vì dùng nguồn thật của công ty.