Phối hợp xoay bí mật webhook

#Mục tiêu

Bạn phối hợp đổi bí mật ký mà không làm mất sự kiện hoặc đưa bí mật vào hội thoại. Agent chuẩn bị và kiểm tra; người có quyền thực hiện bước xoay trên web.

#Quyền cần

• webhooks.read để đọc webhook và lịch sử gửi trong phạm vi được cấp.
• webhooks.manage để gửi thử.
• Quyền vận hành dịch vụ nhận ở phía ngoài, nếu bạn được giao kiểm tra bên nhận.

integrations.manage mở rộng phạm vi webhook nhưng không bỏ rào cản dành riêng cho người.

Thao tác đổi bí mật được đánh dấu humanOnly: true. Nó không nằm trong PUBLIC_OPS, nên không có công cụ MCP công khai hay trang REST thao tác công khai để agent dùng.

#Hỏi người trước khi

Hỏi webhook nào cần đổi, ai cập nhật bên nhận, thời gian chuyển tiếp và nơi lưu bí mật mới.

Nếu nghi bí mật đã lộ, yêu cầu người quyết định có cần tạm dừng webhook trong lúc xử lý hay không. Đừng tự kéo dài việc chấp nhận khoá cũ chỉ để tránh lỗi.

#Kiểm trước

Gọi whoami. Đọc webhooks.get và webhooks.deliveries_list qua tools_run.

Xác nhận đúng URL đích và chủ webhook. Kiểm tra bên nhận có thể đồng thời chấp nhận bí mật cũ và mới không. Không yêu cầu người dán bí mật vào tin nhắn để bạn kiểm tra.

#Các bước

1. Ghi nhận tình trạng gửi trước khi đổi.
2. Thống nhất cách cập nhật kho bí mật bên nhận.
3. Chuẩn bị triển khai bên nhận có thể kiểm nhiều khoá hợp lệ.

4. Nhờ người mở Cài đặt → Webhook và chọn webhook.
5. Nhờ người mở Cài đặt & Bí mật.
6. Nhờ người chọn Xoay bí mật.
7. Nhờ người lưu bí mật mới trực tiếp vào kho bí mật bên nhận.
8. Sau khi bên nhận đã cập nhật, gọi webhooks.test, bằng webhooks_test nếu có hoặc tools_run.
9. Đọc lần gửi thử và kiểm tra kết quả xác thực ở bên nhận.

Thời gian chuyển tiếp mặc định là 24 giờ. Hệ thống cho tối đa 2 khoá đang hoạt động cùng ký; bên nhận chấp nhận chữ ký khớp một khoá hợp lệ.

#Kiểm sau

Kiểm tra sự kiện mới được nhận thành công, không chỉ sự kiện ký bằng khoá cũ. Theo dõi lần gửi sau chuyển đổi và việc xử lý chống trùng.

Khi khoá cũ hết hiệu lực, xác nhận bên nhận vẫn hoạt động với khoá mới. Báo cáo chỉ ghi ID webhook, kết quả và thời điểm; không ghi giá trị bí mật.

#Khi lỗi

Nếu chữ ký không khớp, kiểm tra nguồn bí mật, raw body và thời gian máy. Không tắt xác minh chữ ký để khôi phục tạm.

Nếu đã mất bí mật mới, chuyển người xử lý trên web; agent không có đường đọc lại bí mật bằng API công khai.

#Điều kiện dừng

Dừng khi cần thao tác chỉ dành cho người, không có quyền cập nhật bên nhận, hoặc chưa chứng minh được bên nhận chấp nhận khoá mới.

Xem kiểm chữ ký và giữ bí mật.