---
title: "Webhook không tới hoặc bị từ chối"
locale: vi
url: https://tlg.builera.app/docs/troubleshooting/webhook-failures
verified: 2026-10-24
app_version: "2.0"
---

# Webhook không tới hoặc bị từ chối

Kiểm tra chữ ký, phản hồi HTTP, thời gian xử lý và cách gửi lại sự kiện sau khi sửa bên nhận.


## Triệu chứng

Bên nhận không thấy sự kiện, trả lỗi chữ ký hoặc nhận cùng một sự kiện nhiều lần. Trong app, lượt giao có thể đang chờ thử lại, đã thất bại hoặc webhook đã tự tắt.

Trước hết hãy phân biệt “không tạo lượt giao” với “có giao nhưng bên nhận từ chối”. Bộ lọc, quyền của chủ webhook hoặc phạm vi tài khoản có thể khiến sự kiện không được gửi ngay từ đầu.

## Nguyên nhân thường gặp

| Dấu hiệu | Điều cần kiểm tra |
|---|---|
| Chữ ký không khớp | Sai bí mật, dùng khoá cũ hoặc thay đổi thân yêu cầu trước khi kiểm chữ ký. |
| Lỗi thời gian chữ ký | Đồng hồ bên nhận lệch hoặc yêu cầu được xử lý quá muộn. |
| Timeout | Bên nhận làm quá nhiều việc trước khi trả phản hồi. |
| HTTP 4xx | Địa chỉ, xác thực hoặc hợp đồng nhận không đúng; không phải mã 4xx nào cũng có cùng chính sách thử lại. |
| HTTP 5xx | Bên nhận đang lỗi hoặc quá tải. |
| Không có lượt giao | Bộ lọc không khớp, webhook tạm dừng hoặc chủ webhook mất quyền. |

Thời hạn một yêu cầu webhook là **10 giây**. Bên nhận nên xác minh, ghi nhận bền vững rồi trả 2xx nhanh; xử lý nghiệp vụ dài ở hàng đợi riêng.

## Cách xử lý

1. Mở webhook trong **Cài đặt**.
2. Tìm lượt giao tương ứng với sự kiện bị thiếu.
3. Đọc mã lỗi và từng lần thử.
4. Kiểm tra URL HTTPS và khả năng truy cập từ bên ngoài.
5. Kiểm tra bí mật đang dùng ở cả hai phía.
6. Xác minh chữ ký trên thân yêu cầu nguyên gốc, trước khi sửa hoặc mã hoá lại JSON.
7. Kiểm tra các header `webhook-id`, `webhook-timestamp` và `webhook-signature`.
8. Sửa lỗi bên nhận.
9. Gửi thử trước khi mở lại luồng thật.
10. Chỉ gửi lại hoặc replay sau khi bên nhận đã xử lý chống trùng.

![Trang cấu hình webhook trong workspace Demo](https://tlg.builera.app/docs-media/vi/settings-webhooks.webp "Kiểm tra cấu hình và trạng thái webhook")

App có cơ chế tự tắt khi bên nhận lỗi kéo dài. Trường hợp HTTP 410 được coi là địa chỉ không còn nhận. Việc tắt không chứng minh các sự kiện trước đó đều chưa được bên nhận xử lý.

Gửi lại một lượt giao giữ cùng `webhook-id`. Replay một khoảng sự kiện tạo mã giao mới và đánh dấu `replay: true`. Vì vậy, đừng chỉ dựa vào mã giao mới để kết luận đây là một hành động nghiệp vụ mới.

> [!WARNING]
> Replay có thể làm bên nhận chạy lại tác động nghiệp vụ. Hãy giới hạn phạm vi và chống trùng theo sự kiện trước khi thực hiện.

## Nếu vẫn lỗi

Lưu mã webhook, mã lượt giao, thời điểm, mã HTTP và mã lỗi. Gửi phần phản hồi đã che bí mật; không gửi header chứa thông tin xác thực hoặc bí mật ký.

Nếu webhook không có lượt giao, kiểm tra bộ lọc và quyền của chủ webhook trước khi kiểm tra mạng. Nếu đã nhận HTTP thành công nhưng thiếu kết quả nghiệp vụ, tìm lỗi trong hàng đợi của bên nhận.

Xem [viết bên nhận webhook](https://tlg.builera.app/docs/integrations/webhook-receivers). Có thể tra bằng [chi tiết lượt giao](https://tlg.builera.app/docs/reference/rest/webhooks.deliveries_get), MCP `webhooks_deliveries_get`, hoặc [replay](https://tlg.builera.app/docs/reference/rest/webhooks.replay), MCP `webhooks_replay`.