- Webhook là cách một dịch vụ tự gửi dữ liệu tới địa chỉ của bạn khi có sự kiện, thay vì chương trình của bạn phải hỏi định kỳ xem có gì mới.
- Ai biết địa chỉ nhận cũng gửi được, nên phải soát chữ ký: GitHub ký mỗi lần gửi bằng HMAC SHA-256 trên khóa bí mật và nguyên văn phần thân.
- Cùng một sự kiện có thể tới nhiều lần và không đúng thứ tự; ghi lại mã lần gửi hoặc mã sự kiện đã xử lý để bỏ lần trùng.
- Trả lời nhanh rồi mới làm việc nặng: GitHub ngắt kết nối và coi là thất bại nếu không nhận được mã 2XX trong 10 giây.
Code trong bài là Python, chỉ dùng thư viện chuẩn. Các yêu cầu mẫu trong code là giả lập; phần kiểm dùng cặp giá trị mẫu do GitHub công bố.
Webhook là gì
Hãy hình dung bạn chờ kết quả thi. Cách thứ nhất: cứ mười phút lại mở trang của trường xem đã có điểm chưa. Cách thứ hai: để lại số điện thoại, khi có điểm trường nhắn cho bạn. Trong lập trình, cách thứ nhất gọi là hỏi định kỳ (polling): chương trình của bạn gọi API của dịch vụ theo chu kỳ. Cách thứ hai là webhook: bạn đăng ký một địa chỉ web, và dịch vụ gửi một yêu cầu HTTP chứa dữ liệu về sự kiện tới địa chỉ đó ngay khi sự kiện xảy ra.
Trang giới thiệu webhook của GitHub mô tả đúng ý này: webhook dùng để nhận dữ liệu khi nó xảy ra, thay vì gọi API từng lúc để xem đã có dữ liệu chưa, và bạn chỉ cần bày tỏ mối quan tâm tới sự kiện một lần, lúc tạo webhook. GitHub kể các ví dụ dùng webhook như kích hoạt chạy kiểm thử trên một máy chủ khác khi có người đẩy code, gửi thông báo sang Discord hay Slack khi có nhận xét trên pull request, hay ghi lại sự kiện để kiểm tra về sau.
Ngoài GitHub, bạn sẽ gặp webhook ở rất nhiều nơi: bot Telegram và bot Zalo nhận tin qua webhook, như trong bài bot Telegram có AI; nút Webhook trong n8n cho một dịch vụ bất kỳ gọi vào để chạy workflow; cổng thanh toán như Stripe báo về khi một khoản tiền được trả.
Khi nào dùng webhook, khi nào hỏi định kỳ
Webhook có lợi khi sự kiện xảy ra không đều và bạn muốn biết sớm: không phải gửi hàng nghìn yêu cầu chỉ để nhận câu trả lời "chưa có gì". Đổi lại, nó đòi hỏi bạn có một địa chỉ mà dịch vụ kia gọi tới được từ Internet, tức một máy chủ chạy liên tục, và bạn phải lo chuyện an toàn cho địa chỉ đó.
Hỏi định kỳ hợp với chương trình nhỏ chạy trên máy cá nhân, không có địa chỉ công khai, và chấp nhận trễ vài phút: ví dụ một script mỗi sáng đọc tin mới, như cách lên lịch trong bài cho script tự chạy theo lịch. Nhiều dịch vụ cho chọn một trong hai; bot Telegram chẳng hạn chỉ dùng được một cách tại một thời điểm.
Một cách kết hợp hay gặp: nhận webhook để phản ứng nhanh, và thỉnh thoảng hỏi định kỳ để vớt những sự kiện lỡ mất trong lúc máy chủ của bạn tắt.
Cánh cửa mở ra Internet
Địa chỉ nhận webhook là một đường dẫn công khai. Nếu chương trình cứ thấy yêu cầu tới là làm theo, bất kỳ ai đoán ra hay nhìn thấy địa chỉ đều có thể giả làm dịch vụ kia: gửi một "sự kiện thanh toán" giả, hay nhồi hàng nghìn yêu cầu khiến bạn tốn tiền gọi mô hình AI cho từng cái. Vì vậy các dịch vụ lớn đều cho cách xác minh rằng yêu cầu đúng là do họ gửi.
Tài liệu thực hành tốt của GitHub còn dặn: đừng để thông tin nhạy cảm trong đường dẫn nhận, kể cả khóa API của bạn; hãy dùng HTTPS; và chỉ đăng ký những loại sự kiện thật sự cần, để máy chủ ít việc hơn.
Soát chữ ký HMAC
Cách GitHub làm như sau. Khi tạo webhook, bạn đặt một khóa bí mật, nên là một chuỗi ngẫu nhiên khó đoán. Mỗi lần gửi, GitHub dùng khóa đó và nội dung phần thân để tính một mã băm HMAC SHA-256, gửi kèm trong header X-Hub-Signature-256, luôn bắt đầu bằng sha256=. Phía bạn tính lại mã đó bằng cùng khóa trên đúng phần thân nhận được, rồi so với mã GitHub gửi. Kẻ gian không có khóa thì không tạo được chữ ký đúng, và nếu ai đó sửa dù chỉ một ký tự trong thân, chữ ký sẽ không còn khớp.
Tài liệu nhấn mạnh vài điểm dễ sai:
- Tính trên thân gốc. Phải dùng nguyên văn các byte nhận được, xử lý theo UTF-8. Nếu bạn đọc JSON ra rồi ghi lại thành chuỗi trước khi tính, khoảng trắng hay thứ tự khóa có thể đổi và chữ ký sẽ sai. Tài liệu Stripe cũng dặn không được chỉnh sửa phần thân gốc trước khi soát.
- Không so bằng dấu bằng thông thường. GitHub khuyên dùng phép so sánh thời gian hằng, để kẻ tấn công không đoán dần được chữ ký qua thời gian phản hồi. Trong Python, đó là hàm hmac.compare_digest.
- Không viết khóa vào mã. Khóa bí mật cất ở nơi máy chủ đọc được, như biến môi trường, và không bao giờ đẩy lên kho code.
Stripe làm tương tự nhưng thêm mốc thời gian vào phần được ký, để có thể từ chối một yêu cầu cũ bị gửi lại; theo tài liệu Stripe, thư viện của họ mặc định chấp nhận chênh lệch 5 phút giữa mốc đó và giờ hiện tại, nên đồng hồ máy chủ cần chính xác.
Viết bên nhận bằng Python
Đoạn Python dưới đây làm phần cốt lõi của bên nhận: tính chữ ký từ khóa và thân gốc, so bằng hmac.compare_digest, bỏ những lần gửi đã nhận (theo header X-GitHub-Delivery), bỏ loại sự kiện không cần (theo header X-GitHub-Event), và chỉ khi mọi thứ ổn mới đọc JSON để xếp việc vào hàng đợi.
"""Kiểm một lần gửi webhook trước khi tin nó, theo tài liệu webhook của GitHub.
GitHub ký mỗi lần gửi: header X-Hub-Signature-256 = "sha256=" + HMAC SHA-256 dạng hex,
tính từ khóa bí mật (secret) và NGUYÊN VĂN phần thân (body) nhận được. Bên nhận tính lại và so
bằng phép so sánh thời gian hằng (hmac.compare_digest), không dùng ==.
Ngoài chữ ký, chương trình còn: chỉ nhận loại sự kiện mình cần (header X-GitHub-Event), và bỏ qua
lần gửi trùng mã X-GitHub-Delivery đã xử lý. Các yêu cầu mẫu bên dưới là giả lập.
Chỉ dùng thư viện chuẩn.
"""
import hashlib
import hmac
import json
def tinh_chu_ky(khoa_bi_mat: str, than: bytes) -> str:
return "sha256=" + hmac.new(khoa_bi_mat.encode("utf-8"), than, hashlib.sha256).hexdigest()
def chu_ky_dung(khoa_bi_mat: str, than: bytes, chu_ky_nhan: str) -> bool:
if not chu_ky_nhan:
return False
return hmac.compare_digest(tinh_chu_ky(khoa_bi_mat, than), chu_ky_nhan)
def xu_ly(header, than, khoa_bi_mat, da_xu_ly, su_kien_can=("issues",)):
"""Trả về (mã HTTP, lời nhắn). da_xu_ly là tập mã lần gửi đã nhận, được cập nhật tại chỗ."""
header = {k.lower(): v for k, v in header.items()}
if not chu_ky_dung(khoa_bi_mat, than, header.get("x-hub-signature-256", "")):
return 401, "sai chữ ký, bỏ"
ma = header.get("x-github-delivery", "")
if ma in da_xu_ly:
return 200, "đã nhận lần gửi này rồi, bỏ qua"
su_kien = header.get("x-github-event", "")
if su_kien not in su_kien_can:
return 200, f"không cần sự kiện {su_kien}, bỏ qua"
da_xu_ly.add(ma)
du_lieu = json.loads(than.decode("utf-8"))
# Việc nặng như gọi AI nên đẩy vào hàng đợi để trả lời trong vòng 10 giây.
return 202, f"đã nhận {su_kien}/{du_lieu.get('action')}, xếp hàng xử lý"
if __name__ == "__main__":
KHOA = "khoa-bi-mat-mau-chi-de-thu" # khóa thật để trong biến môi trường, không viết vào mã
than = json.dumps({"action": "opened", "issue": {"title": "Lỗi đọc tệp"}}).encode("utf-8")
hop_le = {"X-Hub-Signature-256": tinh_chu_ky(KHOA, than), "X-GitHub-Delivery": "a1", "X-GitHub-Event": "issues"}
da_xu_ly = set()
print("Lần gửi hợp lệ: ", xu_ly(hop_le, than, KHOA, da_xu_ly))
print("Gửi lại đúng lần đó:", xu_ly(hop_le, than, KHOA, da_xu_ly))
sua_than = than.replace(b"opened", b"closed")
print("Thân bị sửa: ", xu_ly({**hop_le, "X-GitHub-Delivery": "a2"}, sua_than, KHOA, da_xu_ly))
print("Không có chữ ký: ", xu_ly({"X-GitHub-Delivery": "a3", "X-GitHub-Event": "issues"}, than, KHOA, da_xu_ly))
Chạy phần ví dụ, lần gửi hợp lệ được nhận; gửi lại đúng lần đó bị bỏ qua vì trùng mã; thân bị đổi chữ opened thành closed bị từ chối vì sai chữ ký; yêu cầu không có chữ ký cũng bị từ chối. Phần kiểm đi kèm dùng cặp giá trị mẫu GitHub đưa ra trong trang hướng dẫn soát chữ ký: với khóa và thân mẫu đó, chương trình phải cho ra đúng chuỗi chữ ký GitHub công bố. Nếu khớp, bạn biết cách tính của mình đúng trước khi nối vào máy chủ thật.
Trả lời nhanh, làm sau
Theo tài liệu thực hành tốt của GitHub, máy chủ của bạn nên trả về mã 2XX trong vòng 10 giây sau khi nhận; quá thời gian đó, GitHub ngắt kết nối và coi lần gửi là thất bại. Stripe cũng dặn trả mã 2XX ngay, trước mọi xử lý phức tạp có thể làm quá giờ.
Điều này quan trọng khi bên nhận cần gọi mô hình AI, vì một lần gọi có thể mất vài giây đến cả chục giây. Cách làm là tách hai việc: phần nhận chỉ soát chữ ký, ghi sự kiện vào hàng đợi rồi trả lời ngay; một tiến trình khác lấy việc từ hàng đợi ra, gọi AI và làm phần còn lại. GitHub gợi ý vài công cụ hàng đợi, trong đó có thư viện RQ cho Python. Với việc nhỏ, một bảng trong cơ sở dữ liệu hay một thư mục chứa tệp chờ xử lý cũng đủ.
Trùng lặp, thứ tự và lần gửi bị lỡ
Đừng giả định mỗi sự kiện tới đúng một lần và đúng thứ tự. Tài liệu Stripe ghi rõ đầu nhận đôi khi nhận cùng một sự kiện nhiều lần, và Stripe không bảo đảm gửi sự kiện theo thứ tự chúng phát sinh. Khi đầu nhận không trả lời được, Stripe tự gửi lại trong tối đa ba ngày với chế độ thật, giãn dần khoảng cách giữa các lần. GitHub thì để bạn tự yêu cầu gửi lại những lần bị lỡ sau khi máy chủ chạy lại.
Từ đó có ba thói quen:
- Ghi mã đã xử lý. Với GitHub, header X-GitHub-Delivery là mã riêng cho mỗi lần gửi, giúp chống kẻ gian chụp lại một yêu cầu rồi gửi lại. Với Stripe, ghi mã sự kiện. Gặp mã đã có thì trả lời thành công và bỏ qua.
- Cẩn thận khi gửi lại. Tài liệu GitHub lưu ý lần gửi lại theo yêu cầu giữ nguyên mã X-GitHub-Delivery của lần gốc. Nếu bạn ghi mã ngay khi nhận nhưng việc xử lý về sau thất bại, hãy xóa mã đó khỏi danh sách, nếu không lần gửi lại sẽ bị bỏ qua oan.
- Không dựa vào thứ tự. Khi cần trạng thái mới nhất, như đơn hàng đã trả tiền chưa, hãy hỏi lại API của dịch vụ thay vì tin rằng sự kiện tới sau là sự kiện mới hơn.
Kiểm loại sự kiện trước khi xử lý
GitHub có nhiều loại sự kiện, mỗi loại có thể có nhiều hành động, và họ còn thêm loại mới theo thời gian. Tài liệu dặn kiểm loại sự kiện qua header X-GitHub-Event và hành động qua khóa action ở đầu phần thân, trước khi xử lý. Chương trình trong bài chỉ nhận loại issues; loại khác được trả lời thành công rồi bỏ qua, để GitHub không coi là lỗi và không tốn công xử lý.
Ví dụ: tự phân loại báo lỗi trong kho của lớp
Lớp bạn có một kho GitHub chung, sinh viên mở issue để báo lỗi trong bài tập. Bạn muốn khi có issue mới, mô hình AI đọc tiêu đề và gợi ý nhãn như "lỗi đề" hay "hỏi cách làm". Bạn tạo webhook cho kho, chỉ chọn sự kiện issues, đặt khóa bí mật ngẫu nhiên và cất trong biến môi trường của máy chủ. Bên nhận soát chữ ký, bỏ lần gửi trùng, chỉ xếp vào hàng đợi những sự kiện có action là opened, rồi trả lời ngay. Tiến trình nền gọi mô hình và ghi gợi ý thành một bình luận để trợ giảng duyệt, chứ không tự gắn nhãn hay đóng issue. Nội dung issue do người khác viết, nên mô hình chỉ được làm đúng việc gợi ý nhãn.
Nếu không muốn tự dựng máy chủ, bạn có thể dùng nút Webhook của n8n; khi đó vẫn nhớ bật xác thực cho nút đó như bài n8n đã nhắc.
- Nhận webhook mà không soát chữ ký hay xác thực.
- So chữ ký bằng dấu bằng thông thường, hoặc tính chữ ký trên JSON đã đọc ra rồi ghi lại.
- Đặt khóa bí mật trong mã, trong kho code, hoặc trong đường dẫn nhận.
- Gọi mô hình AI ngay trong lúc nhận, để quá 10 giây và bị coi là thất bại.
- Xử lý cùng một sự kiện hai lần vì không ghi mã đã nhận.
- Tin rằng sự kiện tới sau luôn là sự kiện mới hơn.
Câu hỏi thường gặp
Webhook là gì?
Là cách dịch vụ tự gửi yêu cầu HTTP chứa dữ liệu tới địa chỉ của bạn khi có sự kiện.
Webhook khác hỏi định kỳ thế nào?
Hỏi định kỳ là bạn gọi API theo chu kỳ; webhook là dịch vụ gọi bạn khi có chuyện.
Làm sao biết webhook đúng là do GitHub gửi?
Tính HMAC SHA-256 từ khóa bí mật và thân gốc, so với header X-Hub-Signature-256.
Vì sao phải trả lời webhook nhanh?
GitHub coi là thất bại nếu không nhận mã 2XX trong 10 giây; việc nặng nên làm ở nền.
Webhook có thể tới hai lần không?
Có; ghi mã lần gửi hoặc mã sự kiện đã xử lý để bỏ lần trùng.
Học tiếp
Nếu bạn muốn học Python và AI bài bản cùng giảng viên, tham khảo khóa học AI của Big-O Coding.
Khóa AI – Introduction to Machine Learning: nền tảng Máy học từ thuật toán cơ bản đến Neural Networks và LLM, học bằng Python. Học thử buổi 1 miễn phí.


