Webhooks & tích hợp ngoài

Trạng thái hiện tại

Nemo12 không có webhook nào — không nhận vào, không gửi ra.

Rất dễ nhầm hai thứ dưới đây là webhook, nên nói rõ:

Thứ	Là gì	Vì sao không phải webhook
`POST /v1/auth/google`	App gửi ID token của Google lên để đổi lấy session	Client chủ động gọi API của ta. Google không gọi ngược vào hệ thống.
`nemo12-events`	Queue nội bộ	Không rời khỏi Cloudflare account, không có HTTP endpoint (queues)

Nghĩa là hiện không có bề mặt HTTP nào nhận lệnh từ bên thứ ba. Đây là một tài sản an ninh — mất nó phải có lý do xứng đáng.

Dịch vụ	Chiều	Cách dùng
Google Identity	Ra → vào theo request	Xác minh ID token khi đăng nhập (`GOOGLE_CLIENT_ID` trong vars)
Cloudflare AI Gateway `nemo12`	Ra	Mọi lời gọi LLM (ai-registry)
Cloudflare Access	Trước API	Bảo vệ surface nội bộ ở tầng hạ tầng, không phải code

Tình huống	Chiều
Thanh toán / gia hạn gói	Nhận vào
Email/push (delivery, bounce, unsubscribe)	Nhận vào
Trạng thái job crawl đề chạy ngoài (SDD-014)	Nhận vào
Bắn sự kiện học tập sang hệ thống của trường đối tác	Gửi ra

Xác thực chữ ký, không xác thực bằng IP. HMAC theo secret trong Cloudflare Secrets — không bao giờ trong vars hay code (QG-008).
Chống replay — kiểm timestamp, từ chối request cũ hơn 5 phút.
Idempotent theo id của bên gửi. Provider nào cũng gửi lại.
Trả 2xx nhanh, xử lý sau. Nhận → validate → đẩy vào queue → trả 200. Không xử lý nặng trong request webhook.
Đường đi riêng /v1/hooks/{provider} — không dùng chung middleware session; đây không phải người dùng đăng nhập.
Payload là dữ liệu, không phải lệnh. Không bao giờ tin trường role, learner_id, amount từ bên ngoài mà không kiểm chứng lại với nguồn sự thật của chính mình.
Ghi audit log mọi lần nhận (QG-008).

Chỉ gửi tới URL đã đăng ký sẵn, không bao giờ gửi tới URL lấy từ dữ liệu người dùng (chống SSRF).
Ký payload để bên nhận xác minh được.
Không gửi dữ liệu trẻ em ra ngoài khi chưa có consent của phụ huynh (REQ-SEC — child data minimization).
Retry có backoff + DLQ, không retry vô hạn.
Khai vào bảng ở trang này trong cùng PR.