Webhook là cách dịch vụ ngoài như GitHub hay Stripe báo cho API của bạn khi có sự kiện mới — nhưng bất kỳ ai biết URL cũng có thể gửi request giả mạo. Cách chặn là xác minh chữ ký HMAC-SHA256: bên gửi ký lên đúng từng byte của body thô bằng secret chung, server tính lại chữ ký trên body vừa nhận và so sánh hằng thời gian. Chỉ khi chữ ký khớp mới parse JSON và xử lý sự kiện — dùng được cho mọi webhook có secret chung.
Vấn đề
Giả sử bạn viết endpoint nhận webhook GitHub và kiểm tra chữ ký trong header X-Hub-Signature-256. Nhiều người parse JSON trước, rồi dumps lại để tính chữ ký — và đó chính là chỗ hỏng.
import hashlibimport hmacimport jsonfrom fastapi import FastAPI, Requestapp = FastAPI()SECRET = "bi-mat-webhook" # thực tế lấy từ biến môi trường@app.post("/webhook")async def webhook_wrong(request: Request): payload = await request.json() # SAI: json.dumps() sắp xếp lại key và khoảng trắng, # chữ ký tính ra khác với chữ ký của bên gửi body = json.dumps(payload).encode() digest = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest() signature = request.headers.get("X-Hub-Signature-256", "") if digest != signature.replace("sha256=", ""): return {"error": "Chu ky khong hop le"} return {"ok": True}
Cách này hỏng ở ba điểm. Thứ nhất, json.dumps() không trả lại đúng từng byte ban đầu: thứ tự key và khoảng trắng có thể khác, nên chữ ký tính ra không khớp — webhook hợp lệ cũng bị từ chối. Thứ hai, so sánh bằng != để lộ timing attack: kẻ tấn công đo thời gian phản hồi để đoán dần chữ ký. Thứ ba, trả dict lỗi với status 200 khiến bên gửi tưởng webhook đã nhận, trong khi sự kiện chưa hề được xử lý.
Giải pháp
Cách đúng: đọc body thô trước, tính chữ ký trên đúng những byte đó, so sánh bằng hmac.compare_digest, chỉ parse JSON sau khi chữ ký đã khớp.
import hashlibimport hmacimport osfrom fastapi import FastAPI, HTTPException, Requestapp = FastAPI()SECRET = os.environ["WEBHOOK_SECRET"] # không hardcode secret@app.post("/webhook")async def webhook(request: Request): body = await request.body() # đúng từng byte thô bên gửi đã ký signature = request.headers.get("X-Hub-Signature-256", "") expected = "sha256=" + hmac.new( SECRET.encode(), body, hashlib.sha256 ).hexdigest() if not hmac.compare_digest(expected, signature): raise HTTPException(status_code=401, detail="Chu ky khong hop le") payload = await request.json() # chỉ parse SAU khi chữ ký đã khớp print("Nhan su kien:", payload.get("action")) return {"ok": True}
Vì sao đúng? request.body() trả về đúng từng byte bên gửi đã ký, nên chữ ký tính lại luôn khớp khi secret đúng — không phụ thuộc thứ tự key hay khoảng trắng. hmac.compare_digest so sánh trong thời gian hằng số, không để lộ thông tin qua thời gian phản hồi. Secret lấy từ biến môi trường thay vì hardcode, và lỗi xác thực trả về 401. Lưu ý: nếu endpoint vừa khai báo Request vừa khai báo model Pydantic, FastAPI vẫn parse body trước — tốt nhất chỉ nhận Request rồi tự parse sau khi xác minh.
Áp dụng vào dự án của bạn
Áp dụng ngay cho mọi webhook đang chạy không kiểm tra chữ ký: viết một dependency xác minh rồi gắn vào mọi endpoint webhook bằng Depends — viết một lần, dùng chung. Với webhook quan trọng như thanh toán, cộng thêm kiểm tra timestamp trong header (kiểu Stripe): từ chối request có timestamp lệch quá 5 phút để chặn gửi lại. Cuối cùng, log mỗi lần xác minh thất bại kèm IP nguồn để phát hiện ai đang dò endpoint của bạn.
Bài viết liên quan
- FastAPI: đọc Header và Cookie đúng cách bằng Header() và Cookie() trong 5 phút
- FastAPI: bảo vệ route bằng HTTPBearer — xác thực Bearer token không cần OAuth2 trong 5 phút
- FastAPI: dùng `def` hay `async def` cho endpoint? Chọn sai, API chậm cả hệ thống
Câu hỏi thường gặp
Vì sao không được parse JSON rồi dumps lại để tính chữ ký?
Vì JSON linh hoạt: cùng một dữ liệu có thể viết thành nhiều chuỗi byte khác nhau. Bên gửi ký trên chuỗi byte gốc nên chỉ cần dumps lại khác một khoảng trắng là chữ ký đã sai; tính trên body thô thì không bao giờ lệch.
So sánh bằng == có sao không, chữ ký ngắn thế cơ mà?
Có. Toán tử == dừng ngay ở ký tự khác đầu tiên nên thời gian phản hồi tiết lộ vị trí sai; kẻ tấn công đo nhiều lần để đoán dần toàn bộ chữ ký. hmac.compare_digest luôn duyệt hết chuỗi nên không rò rỉ thông tin này.
Header chữ ký có tên khác nhau ở mỗi dịch vụ thì sao?
Mỗi dịch vụ đặt tên riêng — GitHub dùng X-Hub-Signature-256, Stripe dùng Stripe-Signature — nhưng nguyên tắc giống nhau: lấy đúng header đó, tính HMAC trên body thô, so sánh hằng thời gian.
💬 Bạn đã thử cách này trong dự án của mình chưa? Nếu gặp lỗi hoặc có cách làm gọn hơn, để lại bình luận bên dưới — mình đọc hết và sẽ bổ sung những ý hay vào bài.
Nguồn tham khảo
- FastAPI — Using Request Directly: https://fastapi.tiangolo.com/advanced/using-request-directly/
- GitHub Docs — Validating webhook deliveries: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
- Python Docs — hmac: https://docs.python.org/3/library/hmac.html
