---
title: "Phối hợp xoay bí mật webhook"
locale: vi
url: https://tlg.builera.app/docs/agent-playbooks/rotate-webhook-secret
verified: 2026-10-24
app_version: "2.0"
---

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

Agent chuẩn bị và kiểm tra việc đổi bí mật, còn người thực hiện bước xoay trên web.


## 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`](https://tlg.builera.app/docs/reference/rest/webhooks.get) và [`webhooks.deliveries_list`](https://tlg.builera.app/docs/reference/rest/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ệ.

> [!IMPORTANT]
> Điểm dừng — hỏi người
>
> Agent không gọi thao tác xoay bí mật, không dùng `tools_run` để vượt `humanOnly`, và không chuyển sang server function nội bộ. Nhờ người có quyền thực hiện trên web.

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`](https://tlg.builera.app/docs/reference/rest/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ệ.

![Tab cài đặt webhook với vùng bí mật được che kín](https://tlg.builera.app/docs-media/vi/webhook-secret-settings.webp "Bí mật đã được che")

## 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ý](https://tlg.builera.app/docs/integrations/webhook-receivers) và [giữ bí mật](https://tlg.builera.app/docs/safety/keep-secrets).