HLS Video Pipeline

Flow webhook HLS theo góc nhìn nghiệp vụ

Tài liệu này tập trung vào quyết định vận hành và phối hợp liên nhóm. Không thay thế Swagger, không lặp lại schema endpoint. Mục tiêu là giúp mọi bên thống nhất cách hệ thống phản ứng khi HLS gửi sự kiện liên quan đến trạng thái video.

Route: /api/v1/webhooks/hls Bắt buộc verify chữ ký Whitelist event nghiệp vụ
01

Phạm vi và tác nhân

Mục tiêu kinh doanh

Đồng bộ trạng thái video để feed/profile không hiển thị sai tình trạng media.

Tác nhân chính

HLS, Backend API, bảng post_media, và ứng dụng client.

Đầu vào

Webhook event chứa thông tin asset/playback/status, chỉ nhận nếu chữ ký hợp lệ.

Đầu ra

Cập nhật trạng thái media nội bộ hoặc bỏ qua an toàn nếu event ngoài phạm vi.

02

Flow xử lý chính

  1. 1. HLS gửi webhook đến endpoint của backend.
  2. 2. Backend xác thực chữ ký để chặn payload giả mạo.
  3. 3. Hệ thống chỉ xử lý event đã whitelist (ready/errored/deleted).
  4. 4. Event hợp lệ được ánh xạ thành trạng thái media và ghi vào post_media.
  5. 5. API ACK cho HLS, client đọc trạng thái mới để hiển thị đúng UX.
Lưu ý quan trọng: verify chữ ký là hàng rào bảo vệ bắt buộc, không được bypass trong bất kỳ nhánh nghiệp vụ nào.
02A

Giải thích logic express.raw()

Ở src/app.ts có đoạn: app.use('/api/v1/webhooks/hls', express.raw({ type: 'application/json' })). Mục đích là giữ nguyên bytes gốc của payload webhook HLS để verify chữ ký.

HLS ký payload theo raw body

Signature của HLS theo kiểu: HMAC_SHA256(secret, `${timestamp}.${rawBody}`). Tức là hash được tạo trên đúng chuỗi JSON gốc HLS gửi.

Header thường có dạng: x-webhook-signature: t=1710000000,v1=abcdef... với t là timestamp, v1 là HMAC hash.

Vì sao express.json() dễ fail verify

express.json() sẽ parse body thành object JS. Khi stringify lại, thứ tự key, spacing, newline hoặc unicode có thể khác raw payload.

Chỉ cần khác 1 byte là hash khác hoàn toàn → chữ ký mismatch → verify fail.

Bước Dùng express.json() Dùng express.raw() Tác động verify
Nhận body Body thành object JS Body giữ dạng Buffer bytes gốc Raw bytes mới khớp cách HLS ký
Dữ liệu đem hash Phải stringify lại object Dùng trực tiếp rawBody Tránh sai khác do re-serialize
Rủi ro byte-level Dễ đổi key order/spacing Không đổi payload gốc Verify chính xác hơn
Hình dung đơn giản: HLS ký trên “file gốc”. Nếu server mở file rồi lưu lại mới đi verify, bytes đã khác nên chữ ký sẽ không còn khớp.
03

Ma trận quyết định event

Event Xử lý Cập nhật nghiệp vụ Tác động user Ưu tiên
video.asset.ready Có Đánh dấu media sẵn sàng phát. Video hiển thị và phát được. Cao
video.asset.errored Có Đánh dấu lỗi xử lý media. UI hiển thị fallback lỗi. Cao
video.asset.deleted Có Đồng bộ media không còn khả dụng. Ẩn/đánh dấu không tồn tại. Trung bình
Event ngoài danh sách Bỏ qua Không ghi DB, ACK sớm. Không thay đổi UI. Thấp
Chữ ký sai / thiếu Từ chối Không xử lý dữ liệu. Không đổi UI, cần cảnh báo ops. Rất cao
04

Quy ước liên nhóm

Backend

Verify trước, xử lý sau. Event ngoài phạm vi phải trả ACK nhanh và không side-effect.

Frontend

Hiển thị rõ trạng thái uploading/uploaded/failed, không giả định video luôn sẵn sàng ngay.

QA

Test đầy đủ nhánh: event hợp lệ, event bị bỏ qua, chữ ký sai, retry webhook.

Ops

Theo dõi tỉ lệ signature fail, tỉ lệ event lỗi và độ trễ upload đến ready.

05

Rủi ro và phản ứng

Tình huống Dấu hiệu Phản ứng đề xuất
Giả mạo webhook Signature mismatch tăng đột biến Giữ policy từ chối, rà soát secret và log điều tra.
Event đến trễ/lặp Trạng thái media nhảy hoặc cập nhật muộn Đảm bảo cập nhật idempotent và theo dõi retry pattern.
Ready nhưng không phát được Có playback id nhưng client báo lỗi Kiểm tra mapping playback id/CDN và fallback UX.
Nhiều event không hỗ trợ Tỉ lệ event bỏ qua cao bất thường Rà soát cấu hình webhook HLS và cập nhật whitelist nếu cần.
06

Checklist trước release

Security gate

[ ] Thiếu signature bị từ chối. [ ] Signature sai bị từ chối.

Business mapping

[ ] ready → phát được. [ ] errored → fallback. [ ] deleted → trạng thái không khả dụng.

Observability

[ ] Có log truy vết event. [ ] Có metric signature fail và error ratio.

Phối hợp liên nhóm

[ ] FE/QA chốt UX lỗi media. [ ] Ops có ngưỡng cảnh báo bất thường webhook.

Last reviewed: 2026-05-10 · HLS webhook business alignment