Cụm bài Tích hợp bên thứ ba: 1. Chọn nhà cung cấp, webhook và lớp chống ăn mòn · 2. Timeout, retry, circuit breaker và bulkhead
Mỗi tích hợp bên thứ ba (cổng thanh toán, SMS OTP, eKYC, vận chuyển) là một phụ thuộc mình không kiểm soát: chậm, lỗi khó hiểu, gọi webhook trùng, đổi API. Bài này rút ra khuôn chung: đánh giá yêu cầu, chọn nhà cung cấp, chọn kiểu tích hợp, nhận webhook an toàn, bọc nhà cung cấp sau interface của mình, log và test. Ví dụ VNPay QR cụ thể nằm ở bài tích hợp cổng thanh toán và bài IPN tới muộn và đối soát; timeout, retry, circuit breaker, bulkhead nằm ở phần 2.
1. Phân tích yêu cầu: đánh giá theo thứ tự nào
Ý chính: bảo mật, rồi độ tin cậy, rồi hiệu năng (throughput, latency), rồi độ phức tạp. Thứ tự theo chi phí sửa sai: cái nào sai thì mất nhiều nhất được xét trước.
- Bảo mật sai: có thể mất tiền thật, không lấy lại được.
- Độ tin cậy sai: đơn sai trạng thái, phải đối soát tay.
- Hiệu năng kém: còn bù được bằng cache, queue, thêm máy.
- Độ phức tạp: trả dần bằng thời gian kỹ sư.
Bài toán thu tiền online của khoá học
Sản phẩm cần thu tiền online tự động. Yêu cầu: thanh toán tự động, bảo mật cao, phí thấp, nhiều phương thức, cộng yếu tố mềm (ổn định, hỗ trợ kỹ thuật, khuyến mãi, giao diện, tốc độ tích hợp, trang quản lý). Lời giải: tích hợp một cổng thanh toán thay vì làm việc với từng ngân hàng.
1.1. Chọn nhà cung cấp
Không có bên “tốt nhất”: mỗi bên có ưu nhược điểm, lựa chọn phụ thuộc yêu cầu. So sánh theo bảy nhóm: bảo mật, phí, độ tin cậy, tiền về, tích hợp, vận hành, chi phí thoát (đổi sang bên khác). Hai điều hay bị bỏ qua: slide ghi PCI DSS 3.2.1, bản đã hết hiệu lực; và phí trên slide chỉ là ảnh chụp một thời điểm.
Bảng tiêu chí chọn nhà cung cấp, phí trên slide và PCI DSS hiện hành
| Tiêu chí | Câu hỏi cụ thể |
|---|---|
| Bảo mật, tuân thủ | Có chứng nhận PCI DSS phiên bản hiện hành không, mức nào? Ký request bằng gì? Có IP cố định cho callback không? |
| Phí | Phí theo giao dịch (phần trăm + phí cố định), phí cài đặt, phí duy trì, phí hoàn tiền |
| Độ tin cậy | SLA uptime, lịch bảo trì, lịch sử sự cố, có API truy vấn trạng thái không, callback retry thế nào |
| Tiền về | Settlement (tiền về tài khoản merchant) T+1 hay T+n, đối soát bằng file hay API |
| Tích hợp | Tài liệu, sandbox, SDK, phiên bản API, thời gian để chạy được luồng đầu tiên |
| Vận hành | Hỗ trợ kỹ thuật, trang quản lý, hoàn tiền một phần, báo cáo |
| Thoát | Đổi nhà cung cấp tốn bao nhiêu: token thẻ có mang đi được không, hợp đồng có ràng buộc không |
Slide liệt kê mức tuân thủ và biểu phí QR nội địa của năm cổng phổ biến tại thời điểm làm slide: phí khoảng 1,1% cộng vài nghìn đồng mỗi giao dịch, có bên thu thêm phí cài đặt và phí duy trì hằng tháng. Số này đổi theo hợp đồng và thời điểm. Dùng bảng như khuôn để tự điền, không như dữ liệu tham khảo.
2. Đồng bộ hay bất đồng bộ
Ý chính: việc bên thứ ba làm xong ngay thì gọi đồng bộ; việc lâu thì gọi đồng bộ để tạo yêu cầu, rồi nhận kết quả bất đồng bộ. Luồng VNPay QR là ví dụ: tạo URL thanh toán đồng bộ (bước 4), kết quả về qua IPN server-to-server (bước 9.1) và qua trình duyệt quay về (bước 9.2).
Khuôn này đúng cho thanh toán, eKYC, xuất hoá đơn, giao hàng.
flowchart LR
A[Backend của mình] -->|1. Gọi đồng bộ tạo yêu cầu| B[Bên thứ ba]
B -->|2. Webhook khi xong| A
A -->|3. Hỏi trạng thái khi webhook trễ| B
J[Job định kỳ] -->|4. Quét yêu cầu treo| A
| Kiểu | Khi nào dùng | Cái giá |
|---|---|---|
| Gọi đồng bộ, chờ kết quả | Tác vụ nhanh (dưới 1–2 giây), cần kết quả ngay: tỉ giá, kiểm tra địa chỉ | Latency và lỗi của họ thành của mình |
| Gọi đồng bộ để tạo, kết quả qua webhook | Tác vụ lâu hoặc chờ người dùng: thanh toán, eKYC | Lộ endpoint công khai; xử lý trùng, sai thứ tự, mất webhook |
| Gọi đồng bộ để tạo, polling trạng thái | Họ không có webhook, hoặc mình không mở được endpoint | Tốn request, trễ theo chu kỳ poll, dễ bị rate limit |
| Đưa vào queue của mình, worker gọi ra | Người dùng không cần chờ: email, SMS thông báo, đẩy đơn sang hãng vận chuyển | Thêm broker, trạng thái trung gian, cần dead letter |
Webhook là bên thứ ba chủ động gọi endpoint của mình khi có sự kiện; polling là mình định kỳ hỏi họ. Kiểu queue + worker tách latency của bên thứ ba khỏi request người dùng và làm phẳng đỉnh tải; cách chọn broker ở bài message broker.
3. Nhận webhook an toàn
Ý chính: webhook là endpoint công khai, ai cũng gọi được. Kiểm chữ ký trên body thô, chặn phát lại, lưu rồi trả lời nhanh, và chịu được trùng lẫn sai thứ tự.
Danh sách kiểm tra, theo thứ tự xử lý:
- Kiểm chữ ký trên body thô. Bên gửi ký bằng HMAC (mã băm có khoá bí mật chung) với secret riêng cho mình, hoặc chữ ký số kiểm bằng khoá công khai của họ. Nó bảo đảm cùng lúc toàn vẹn và nguồn gốc; so sánh HMAC với chữ ký số ở bài encoding, hash và chữ ký.
- Chống phát lại (replay: kẻ xấu gửi lại một request hợp lệ cũ). Chữ ký đúng không có nghĩa là lần đầu. Timestamp nằm trong phần được ký; lệch quá 5 phút thì từ chối. Kèm dedupe theo event id.
- Lọc IP nguồn theo danh sách nhà cung cấp công bố, chỉ là lớp phụ, không thay chữ ký.
- Lưu nguyên văn, trả lời nhanh: ghi event vào DB (hoặc outbox) rồi trả 2xx, xử lý nặng chạy sau. Xử lý lâu là bị gửi lại.
- Trả đúng mã theo tài liệu, vì mã quyết định họ có retry không. Theo slide: thành công trả
00, không tìm thấy đơn trả01, và ít nhất có try/catch để lỗi không thành stack trace.
Code kiểm chữ ký dưới đây đã chạy thử với JDK 21. MessageDigest.isEqual so sánh trong thời gian hằng, để kẻ tấn công không đoán dần chữ ký qua thời gian phản hồi.
static String sign(byte[] secret, long ts, String body) throws Exception {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret, "HmacSHA256"));
return HexFormat.of().formatHex(mac.doFinal((ts + "." + body).getBytes(StandardCharsets.UTF_8)));
}
static String verifyWebhook(byte[] secret, String tsHeader, String sigHeader, String body, Clock clock) throws Exception {
long ts;
try { ts = Long.parseLong(tsHeader); } catch (NumberFormatException e) { return "reject: bad timestamp"; }
if (Math.abs(clock.instant().getEpochSecond() - ts) > 300) return "reject: outside 5-minute window";
byte[] expected = HexFormat.of().parseHex(sign(secret, ts, body));
byte[] given;
try { given = HexFormat.of().parseHex(sigHeader); } catch (IllegalArgumentException e) { return "reject: bad signature format"; }
return MessageDigest.isEqual(expected, given) ? "accept" : "reject: signature mismatch";
}
// hợp lệ: accept; sửa body: signature mismatch; gửi lại sau 10 phút: outside 5-minute window (đã chạy thử)
Bên gửi retry thế nào: VNPay gửi lại IPN khi merchant trả 01, 04, 97, 99 hoặc không trả lời kịp, tối đa 10 lần trong khoảng 5 phút (theo slide; đối chiếu tài liệu hiện hành). Vậy handler nhận trùng, lần lượt hoặc đồng thời, nên phải idempotent và an toàn khi chạy song song. Cách làm bằng UPDATE ... WHERE status = 'PENDING' và unique constraint ở bài idempotency phần 2.
4. Lớp chống ăn mòn: đừng để model của họ lan vào hệ thống
Ý chính: đặt mỗi bên thứ ba sau một anti-corruption layer: interface do mình định nghĩa bằng ngôn ngữ nghiệp vụ của mình, cộng một adapter cho từng nhà cung cấp lo ký, gọi và ánh xạ mã lỗi.
Lỗi hay gặp: DTO và mã trạng thái của nhà cung cấp chảy thẳng vào code nghiệp vụ, kiểu if (resp.getVnpResponseCode().equals("00")) rải khắp service đặt hàng. Đổi nhà cung cấp là sửa khắp nơi. Code dưới là phác thảo, chưa chạy.
public interface PaymentGateway {
CheckoutSession createCheckout(PaymentAttempt attempt); // URL hoặc QR
GatewayStatus queryStatus(String attemptRef); // cho job đối soát
WebhookOutcome parseCallback(Map<String, String> rawParams); // kiểm chữ ký + ánh xạ
}
public sealed interface GatewayStatus {
record Paid(long amountMinor, String providerTxnId, Instant paidAt) implements GatewayStatus {}
record Failed(String reason) implements GatewayStatus {}
record Pending() implements GatewayStatus {}
record Unknown(String rawCode) implements GatewayStatus {} // mã lạ: không đoán, báo động
}
Adapter là nơi duy nhất biết vnp_ResponseCode, đơn vị tiền nhân 100, cách encode khi ký. Đây là pattern Adapter áp vào ranh giới hệ thống.
Việc khác của lớp adapter: phiên bản, secret, mã lạ
- Ghim phiên bản API và thư viện: bắt đầu bằng bản mới nhất được hỗ trợ, sau đó nâng có kiểm soát. Bật quét lỗ hổng phụ thuộc (Dependabot, OWASP Dependency-Check), vì SDK của nhà cung cấp kéo theo cả cây thư viện.
- Secret riêng cho từng môi trường và từng nhà cung cấp, nằm trong secret manager, xoay được.
- Mã lạ thành
Unknownvà báo động, không mặc định thành công hay thất bại.
5. Log và tracing cho từng bước
Ý chính: log đầu vào và đầu ra của từng bước, cả nhánh thành công, thất bại và exception. Khi khách báo “trả tiền rồi mà đơn vẫn chờ”, người trực phải biết trong vài phút request đã đi tới bước nào.
Xem cả log Nginx ở bước trình duyệt quay về. Tối thiểu cần:
- Một dòng log có cấu trúc cho mỗi lời gọi ra và mỗi webhook vào, có mã tham chiếu của mình và mã giao dịch của họ.
- Bản nguyên văn request/response quan trọng trong bảng riêng, cho đối soát và tranh chấp.
- Metric riêng cho từng nhà cung cấp, và trace id truyền qua lời gọi ra.
Chi tiết: field log, bảng lưu nguyên văn, metric và trace id
- Dòng log có cấu trúc gồm: nhà cung cấp, thao tác, mã tham chiếu của mình, mã giao dịch của họ, HTTP status, mã nghiệp vụ, thời gian, số lần thử, trace id.
- Lưu nguyên văn request và response quan trọng (đã che dữ liệu nhạy cảm) vào bảng riêng, vì log tập trung có thời gian lưu ngắn.
- Metric theo từng nhà cung cấp: latency p50/p99, tỉ lệ lỗi theo mã, trạng thái circuit breaker, số webhook bị từ chối chữ ký. Cảnh báo khi p99 tiến gần timeout của họ hoặc tỉ lệ lỗi tăng.
- Truyền trace id qua header
traceparentnếu họ hỗ trợ; tối thiểu gửi mã tham chiếu của mình để tra chéo. Cách dựng tracing ở bài distributed tracing.
6. Test tích hợp
Ý chính: sandbox cho luồng đầu cuối, server giả lập trong CI cho lỗi mà sandbox không tạo được, và test cố định cho chữ ký và ánh xạ để không vỡ âm thầm.
- Sandbox: thành công, khách huỷ, sai OTP. Chi tiết ở bài đối soát.
- Server giả lập (WireMock, MockWebServer,
HttpServercủa JDK như ở phần 2): chậm hơn timeout, 503 rồi 200, mã lạ, đứt kết nối giữa chừng, webhook trùng và sai thứ tự. - Vector chữ ký cố định: payload, secret, chữ ký mẫu từ tài liệu của họ.
- Contract test cho adapter: response mẫu thật (đã che) phải ánh xạ đúng; họ đổi API thì test đỏ trước production.
Bài tập
Bài 1: Thiết kế tích hợp eKYC
Dịch vụ eKYC nhận ảnh CCCD và ảnh chân dung, trả kết quả sau 5–60 giây qua webhook, không có API hỏi trạng thái theo lô nhưng có API hỏi theo từng yêu cầu. Thiết kế luồng.
Lời giải Bài 1: luồng eKYC bất đồng bộ
- Bảng
kyc_request(id, user_id, provider_ref, status, created_at, updated_at), trạng tháiSUBMITTED → PROCESSING → APPROVED | REJECTED | NEEDS_REVIEW. - Nộp: người dùng upload; backend lưu ảnh (mã hoá, xem phần lưu dữ liệu cá nhân), tạo bản ghi, đưa lệnh gọi vào queue.
- Worker gọi nhà cung cấp với idempotency key là
kyc_request.id, có timeout và retry có jitter, lưuprovider_ref. - Webhook: kiểm chữ ký trên body thô và timestamp, lưu nguyên văn, chuyển trạng thái có điều kiện (chỉ đi tiến), trả 2xx ngay.
- Job mỗi phút hỏi trạng thái các yêu cầu
PROCESSINGquá 2 phút, có giới hạn tốc độ để không vượt quota. - Frontend hiển thị “đang xác minh”, nhận kết quả bằng polling backend của mình hoặc server-sent events.
- Mã lạ thành
NEEDS_REVIEWcho người duyệt tay. - Metric: thời gian từ nộp tới kết quả; tỉ lệ webhook bị mất (kết quả tới từ job thay vì webhook).
Ghi nhớ
- Giải thích được vì sao đánh giá bảo mật trước, độ phức tạp sau cùng.
- Biết khi nào gọi đồng bộ, khi nào webhook, polling hay queue, và vì sao nên dùng cả webhook lẫn polling.
- Liệt kê được năm bước nhận webhook an toàn, và vì sao phải kiểm chữ ký trên body thô.
- Biết xử lý webhook trùng, đồng thời và sai thứ tự.
- Giải thích được anti-corruption layer giữ gì ra khỏi code nghiệp vụ, và vì sao mã lạ phải thành
Unknown.
Câu hỏi phỏng vấn
Junior
Webhook là gì và khác polling thế nào?
Webhook là bên thứ ba chủ động gọi endpoint của mình khi có sự kiện; polling là mình định kỳ hỏi họ.
Webhook nhanh, tiết kiệm request, nhưng có thể mất, trùng, sai thứ tự, và cần endpoint công khai bảo vệ bằng chữ ký. Polling chắc hơn nhưng chậm và tốn quota. Hệ thống tốt dùng webhook làm đường chính, polling làm lưới an toàn.
Vì sao handler webhook hay IPN phải idempotent?
Vì bên gửi giao theo at-least-once, nên cùng một sự kiện có thể tới nhiều lần, kể cả hai lần cùng lúc.
Họ gửi lại khi không nhận được phản hồi hợp lệ kịp (cổng kiểu VNPay gửi lại tối đa khoảng 10 lần trong 5 phút). Handler không idempotent sẽ cộng tiền hai lần, trừ kho hai lần. Dedupe theo event id và chuyển trạng thái bằng UPDATE có điều kiện để lần thứ hai không làm gì.
Mid
Bảo vệ endpoint webhook thế nào?
Kiểm chữ ký trên body thô, chặn phát lại bằng timestamp đã ký và event id, lưu rồi trả 2xx nhanh.
- Kiểm HMAC (hoặc chữ ký số) trên body thô, so sánh thời gian hằng.
- Kiểm timestamp trong phần được ký; dedupe theo event id.
- Lọc IP nguồn như lớp phụ.
- Lưu nguyên văn, trả 2xx nhanh, xử lý sau.
- State machine chỉ đi tiến để chịu được trùng và sai thứ tự.
- Trả đúng mã theo tài liệu, vì nó quyết định họ có retry không.
Vì sao nên bọc nhà cung cấp sau một interface của mình?
Để mã trạng thái, DTO, đơn vị tiền và cách ký của nhà cung cấp không lan vào code nghiệp vụ (anti-corruption layer).
Đổi hoặc thêm nhà cung cấp chỉ cần thêm adapter. Test nghiệp vụ dùng fake của interface. Mã lạ được ánh xạ thành Unknown có báo động thay vì bị hiểu nhầm là thành công.
Webhook refunded tới trước succeeded. Bạn xử lý thế nào?
Không áp theo thứ tự tới: state machine chỉ cho chuyển tiến, event cũ tới sau bị bỏ qua thay vì ghi đè.
Chuyển trạng thái bằng UPDATE có điều kiện trên trạng thái hiện tại. Khi event không khớp trạng thái hiện tại, coi nó là tín hiệu, gọi API của nhà cung cấp lấy trạng thái mới nhất, rồi áp qua cùng hàm cập nhật. Lưu nguyên văn mọi event để điều tra.
Senior
Bạn chọn giữa hai cổng thanh toán thế nào, và làm sao để sau này đổi được?
Đánh giá theo bảo mật, độ tin cậy, hiệu năng, độ phức tạp, cộng chi phí, ghi vào ADR; giữ khả năng đổi bằng interface và adapter của mình.
- Tiêu chí: PCI DSS hiện hành (xin AOC), cách ký và bảo vệ callback, SLA và lịch sử sự cố, API truy vấn và file đối soát, thời gian settlement, phí tổng (theo giao dịch, cố định, hoàn tiền), chất lượng sandbox và hỗ trợ.
- Ghi quyết định vào ADR kèm ngày lấy số liệu.
- Để đổi được: interface
PaymentGateway, adapter riêng, bảng payment attempt độc lập với nhà cung cấp, không lưu dữ liệu thẻ (redirect hoặc field nhúng), contract test cho mỗi adapter.
Tích hợp eKYC trả kết quả sau 5–60 giây. Đồng bộ hay bất đồng bộ?
Bất đồng bộ: giữ request người dùng 60 giây là giữ thread, dễ timeout ở load balancer và không chịu được retry.
Gọi tạo yêu cầu qua queue và worker, idempotency key là id yêu cầu. Nhận kết quả qua webhook có kiểm chữ ký, kèm job hỏi trạng thái cho yêu cầu treo quá hạn. Frontend thấy “đang xác minh” và hỏi backend của mình (polling hoặc server-sent events), không hỏi thẳng nhà cung cấp.
Từ vựng tiếng Anh
| Term | Phát âm | Nghĩa | Ví dụ câu tiếng Anh dùng trong phỏng vấn |
|---|---|---|---|
| webhook | /ˈweb.hʊk/ | lời gọi ngược khi có sự kiện | “We verify the webhook signature on the raw body.” |
| replay attack | /ˈriː.pleɪ əˈtæk/ | tấn công phát lại | “A signed timestamp protects the webhook against replay attacks.” |
| anti-corruption layer | /ˌæn.t̬i kəˈrʌp.ʃən ˈleɪ.ɚ/ | lớp chống ăn mòn | “The anti-corruption layer keeps the provider’s status codes out of our domain.” |
| reconciliation | /ˌrek.ən.sɪl.iˈeɪ.ʃən/ | đối soát | “Daily reconciliation catches whatever the webhooks missed.” |
| idempotency key | /ˌaɪ.dəmˈpoʊ.tən.si kiː/ | khoá idempotent | “We resend the payment with the same idempotency key.” |
| settlement | /ˈset̬.əl.mənt/ | tiền về tài khoản merchant | “Settlement lands the next business day, minus fees.” |
| attestation of compliance | /ˌæt.esˈteɪ.ʃən əv kəmˈplaɪ.əns/ | văn bản xác nhận tuân thủ | “Ask the provider for a current PCI DSS attestation of compliance.” |
| raw body | /rɑː ˈbɑː.di/ | body thô chưa parse | “Verify the signature on the raw body before parsing it.” |
Ghi chép dựa trên khoá Advanced Backend (Ronin Engineer), viết lại theo cách hiểu của mình.