Telegram Webhook secret_token và HMAC: bên nhận cần xác minh điều gì?
secret_token trong Telegram Bot API không phải chữ ký HMAC. Khi bạn cấu hình qua setWebhook, Telegram gửi lại cùng giá trị đó trong header X-Telegram-Bot-Api-Secret-Token. Bên nhận so sánh nó với token đã cấu hình. Webhook của UnifyPort dùng một quy tắc khác: khi bật ký, cần tính HMAC-SHA256 từ dấu thời gian và các byte gốc của nội dung yêu cầu, rồi xác minh X-Device-Signature. Hai cách kiểm tra này không thể thay thế nhau.
Những điểm cần phân biệt
- Header của Telegram chứa trực tiếp thông tin bí mật dùng chung, không phải giá trị băm được tính từ JSON.
- Chữ ký UnifyPort dùng
signing_secretcủa endpoint để ràng buộc nội dung gốc vớiX-Device-Timestamp. - Cả hai cách vẫn cần HTTPS, bảo vệ bí mật và xử lý lặp theo tính idempotent.
- Chọn cơ chế xác minh theo cấu hình route đáng tin cậy, không dựa vào trường
providerchưa được xác minh hoặc header nào tình cờ xuất hiện.
Bài viết này tập trung vào xác thực yêu cầu, không phải lựa chọn danh tính nhắn tin. Nếu bạn vẫn đang chọn giữa bot và tài khoản nhắn tin hiện có, hãy xem Telegram Bot API webhook so với webhook nhận tin hợp nhất.
Telegram secret_token thực sự xác minh điều gì?
Tài liệu Telegram Bot API chính thức mô tả secret_token là tham số tùy chọn của setWebhook. Độ dài hợp lệ là 1–256 ký tự, chỉ gồm A-Z, a-z, 0-9, _ và -. Khi được cấu hình, Telegram gửi giá trị này trong X-Telegram-Bot-Api-Secret-Token với mỗi yêu cầu webhook.
Nếu bên nhận bắt buộc áp dụng biện pháp này, yêu cầu thiếu header hoặc có giá trị không khớp không được đi vào hàng đợi đáng tin cậy. Giá trị khớp cho biết bên gửi đang giữ token đã cấu hình. Nó không tạo ra mối liên kết mật mã riêng giữa token và nội dung yêu cầu.
Sự khác biệt này quan trọng tại proxy hoặc dịch vụ chuyển tiếp. Thành phần đọc được token có thể gửi cùng token với nội dung khác. HTTPS bảo vệ kết nối truyền tải, nhưng header tĩnh tự nó không phát hiện thay đổi nội dung sau điểm kết thúc TLS. Đây là khác biệt về ranh giới tin cậy, không phải lý do để bỏ Bot API chính thức.
Nên tạo thông tin bí mật riêng cho webhook, không dùng lại bot token và không dán bí mật vào dịch vụ thu thập yêu cầu công khai. Hãy che giá trị trong nhật ký truy cập, dữ liệu tracing xuất ra và ảnh chụp gửi cho bộ phận hỗ trợ.
Header tĩnh và chữ ký nội dung
HMAC là cơ chế xác thực thông điệp bằng khóa bí mật dùng chung. Theo quy tắc được UnifyPort công bố, bên nhận phải tính lại giá trị băm từ đầu vào xác định, thay vì so sánh trực tiếp header chữ ký với khóa bí mật.
| Câu hỏi | Telegram Bot API webhook | Webhook UnifyPort đã bật ký |
|---|---|---|
| Cấu hình | setWebhook.secret_token | signing_secret của endpoint |
| Header cần xác minh | X-Telegram-Bot-Api-Secret-Token | X-Device-Signature |
| Giá trị nhận được | Chính token đã cấu hình | HMAC-SHA256 dạng thập lục phân |
| Có bao gồm nội dung không? | Không | Có, các byte gốc |
| Có bao gồm dấu thời gian không? | Không | Có, X-Device-Timestamp |
| Thao tác phía nhận | So sánh header với token | Tính lại và so sánh giá trị băm |
| Bảo đảm chỉ xử lý một lần? | Không | Không |
Đầu vào ký của UnifyPort phải đúng dạng:
<X-Device-Timestamp>.<raw request body>Dấu thời gian dùng định dạng RFC 3339 UTC; dấu chấm ở giữa là ký tự phân cách thực tế. Định dạng lại JSON, thay đổi khoảng trắng hoặc phân tích rồi tuần tự hóa lại có thể làm thay đổi các byte đã ký. signing_secret là khóa HMAC, không phải giá trị mà header chữ ký phải bằng trực tiếp.
Nếu signing_secret rỗng, UnifyPort tắt ký và không gửi X-Device-Signature. Bên nhận bắt buộc có chữ ký nên từ chối yêu cầu này, không tự chuyển sang cách xác thực khác.
Tách hai đường nhận dữ liệu
Một thiết kế thực tế là dùng route ứng dụng riêng cho cập nhật Telegram gốc và sự kiện UnifyPort. Đây là khuyến nghị thiết kế ứng dụng, không phải endpoint mới của nhà cung cấp. Khi đưa Telegram cùng Zalo hoặc WhatsApp vào một hàng đợi hỗ trợ, hãy xác minh từng đường vào trước khi hợp nhất công việc.
- Gắn route với nguồn gửi và thông tin bí mật. Cấu hình rõ cơ chế xác minh trước khi nhận lưu lượng.
- Xác thực trước khi chuyển xử lý. Telegram cần vượt qua kiểm tra header token; UnifyPort đã bật ký cần vượt qua kiểm tra HMAC nội dung gốc và độ mới của dấu thời gian.
- Kiểm tra đúng cấu trúc dữ liệu. Không chuyển Telegram
Updategốc cho bộ xử lý đang chờ cấu trúc UnifyPortmessage.received. - Lưu bền vững công việc đã nhận. Tách xác thực yêu cầu, xử lý idempotent và phân quyền nghiệp vụ thành các bước riêng.
- Ghi loại lỗi, không ghi bí mật. Nhật ký chỉ cần chỉ ra phép kiểm tra nào thất bại.
Tránh middleware kiểu “header nào hợp lệ cũng chấp nhận” trên cùng một route. Nhánh yếu hơn hoặc vô tình được bật sẽ trở thành lựa chọn thay thế cho chính sách xác minh dự kiến. Đặc biệt, token Telegram không được thay thế HMAC bắt buộc trên route UnifyPort.
Chi tiết triển khai quy tắc thứ hai có trong hướng dẫn HMAC chống phát lại và xử lý gửi lại. Thời gian nằm trong JSON của tin nhắn không thay thế được dấu thời gian có chữ ký bảo vệ ở lớp phân phối.
Kiểm thử trước khi đưa vào vận hành
Dưới đây là các phép thử đề xuất, không phải kết quả đã thực hiện. Hãy chạy trong môi trường cách ly với thông tin bí mật do bạn quản lý.
| Phép thử | Hành vi mong đợi |
|---|---|
| Header Telegram thiếu hoặc sai | Từ chối trước khi xử lý trong vùng tin cậy |
| Token Telegram đúng nhưng nội dung bị thay đổi | Chỉ kiểm tra header sẽ không phát hiện; vẫn cần kiểm tra dữ liệu và ranh giới truyền tải đáng tin cậy |
| Nội dung UnifyPort bị đổi sau khi ký | Từ chối vì giá trị băm không khớp |
| Chữ ký UnifyPort hợp lệ nhưng thời gian ngoài cửa sổ cho phép | Từ chối theo chính sách độ mới |
| Gửi token Telegram đến route UnifyPort | Từ chối, không đổi cơ chế xác minh |
| Sự kiện thông thường hợp lệ được gửi lại | Tiếp nhận theo tính idempotent, không lặp hành động nghiệp vụ |
Chọn cửa sổ thời gian dựa trên độ chính xác đồng hồ và điều kiện phân phối của hệ thống, thay vì sao chép giá trị của nhà cung cấp khác. Xác thực thành công cũng không đồng nghĩa được phép thực hiện mọi lệnh chứa trong tin nhắn.
Vai trò và giới hạn của UnifyPort
Giao diện không chính thức của UnifyPort cung cấp sự kiện chuẩn hóa từ các tài khoản nhắn tin đã kết nối. HMAC bảo vệ đoạn từ UnifyPort đến bên nhận của bạn. Đây không phải chữ ký gốc của Telegram, cũng không phải bằng chứng đầu cuối về tác giả là người dùng Telegram.
Nếu sản phẩm vốn là bot Telegram, hãy triển khai biện pháp bảo vệ theo tài liệu Telegram tại đường vào đó. Không cần đổi nền tảng chỉ để dùng cơ chế xác thực khác. Nếu dùng UnifyPort cho hàng đợi cấp tài khoản hoặc đa kênh, hãy tuân theo quy tắc riêng và bật ký khi tạo webhook endpoint.
Câu hỏi thường gặp
Có cần tính HMAC bằng Telegram secret_token không?
Không, nếu mục đích là xác minh header bí mật được Bot API mô tả. Hãy so sánh header với token đã cấu hình. Đừng tự đặt ra thuật toán ký nội dung cho header đang truyền chính token đó.
Có thể so sánh trực tiếp X-Device-Signature với signing_secret không?
Không. Tính HMAC-SHA256 từ dấu thời gian và nội dung gốc theo tài liệu, sau đó so sánh kết quả với chữ ký thập lục phân nhận được.
Một trong hai cơ chế có ngăn xử lý trùng không?
Không. Xác thực và loại bỏ trùng lặp là hai việc khác nhau. Lưu công việc đã nhận và giữ các thao tác phía sau có tính idempotent. HMAC tự nó không bảo đảm phân phối đúng một lần.
Bước tiếp theo và nguồn
Dùng tài liệu phân phối webhook và xác minh chữ ký làm đặc tả triển khai cho bên nhận UnifyPort.
Ngày đối chiếu nguồn: 2026-09-17.
Biến tích hợp nhắn tin thành một pipeline sản phẩm ổn định.
Bắt đầu bằng cách gửi qua một API, rồi đưa mọi tin nhắn inbound trở lại hệ thống kinh doanh bằng sự kiện chuẩn.