Joy Loyalty · Integrations
Cái gì đang hỏng, vì sao, và những việc cần làm để mọi integration gửi được dữ liệu, tự phục hồi và báo cho merchant biết.
Vấn đề qua con số · log prod 02/11 → 19/11
authorization Mailchimp của merchant. Địa chỉ khách Recharge và header Apple Wallet cũng bị lộok thay vì JSONSố liệu là số dòng log, không phải số khách duy nhất. Không đưa shop id hay email vào bộ slide này.
Một nguyên nhân đứng sau tất cả
Joy không có module integration. Mỗi app được nối tay qua ~30 file, chạy trên đường không retry được, không có delivery id, không có dead-letter queue, không có trạng thái health, không có metric thành công.
Compute, Pub/Sub và Cloud Tasks thừa sức gánh thêm 5–8 đối tác. Cái thiếu là mọi thứ giúp một lần gửi an toàn.
Vì sao làm mới thay vì vá từng chỗ
Thay đổi cốt lõi, nhìn qua một lần gửi
Hiện tại
retry:falseundefined; dispatcher trả 'ok'Sau khi làm mới
deliveryId cố định, rồi mới xác nhậnAuth cũng theo cùng cách: 401 thành auth_broken (dừng gọi, giữ token, báo merchant), thay vì retry hàng tuần.
1 · Integration đang dùng · đếm trên Firestore prod, chỉ đọc, 20/11
Bản thân số đếm cho thấy điều gì
bản ghi integration vs cờ trên shop
bản ghi integration vs cờ trên shop
kết nối nằm trên shop đã gỡ Joy
kết nối trên shop đã gỡ Joy, khớp với các lần refresh token chết
Hiện tại
Đọc từ code tại HEAD 2ff18f82dc.
2.1 · Một integration đang được nối như thế nào
Id app nằm chung với hằng số loyalty program; event, message, job type ở chỗ khác. Id dùng bốn kiểu viết hoa khác nhau.
const/programs/integrationPrograms.js
Connect/disconnect ở repository, các đường controller, danh sách fan-out, map handler Cloud Task, và card, route, map trạng thái phía admin.
subscribeBackgroundHandling.js: 212 case, 9.933 dòng
Cờ shop statusConnected* (19 tên), isConnected của doc, map dự phòng admin, map AI tool. Chúng lệch nhau, đã đo được.
Connect callback, disconnect, side effect của repo, auto-disconnect Klaviyo (có revoke!), lỗi auth Intercom, lỗi bulk Drip, update chung.
2.2 · Đường gửi ra hiện tại, và chỗ dữ liệu bị mất
triggerIntegrationAppServiceretry: false. Một dispatcher 212 casemaxAttempts: 1, không đặt rateLimitsChiều nhận vào cũng không khá hơn: bốn nguồn review không ký, hai verifier fail-open, Recharge không xác thực, và webhook Shopify sai HMAC vẫn trả 200 mà không ghi log.
3.2 · Hạ tầng theo từng loại integration
| Loại | App | Đang chạy trên | Khi gặp 401 / 429 / 5xx |
|---|---|---|---|
| Email / SMS marketing (gửi ra) | Klaviyo, Omnisend, Mailchimp, Attentive, Drip, Sendlane, PushOwl | Pub/Sub Light/Small (retry:false) → service; Klaviyo re-enqueue trên queue chung; bulk collector cho Klaviyo | Throttle gate, 3 lần rồi bỏ; chỉ private key Klaviyo tự disconnect khi 401 |
| Helpdesk / nhắn tin | Gorgias, Intercom, LINE, Smax | Cùng đường Pub/Sub; Gorgias giới hạn trong RAM | Gorgias refresh lỗi → vòng lặp TypeError; LINE retry không có idempotency key |
| Review (nhận vào) | Judge.me, Yotpo, Loox, Stamped, Fera, Review Rocket, Air Reviews, Klaviyo Reviews | Webhook HTTP trên apiHookV2, xử lý inline; dedupe chung | 4 nguồn không ký, 2 fail-open |
| Subscription / wishlist | Recharge, Joy Subscription, Joy Wishlist | HTTP nhận vào + gọi ra | Recharge không xác thực, lấy tenant từ query, PII trong log |
| Mạng xã hội | Instagram, Facebook Page | Webhook Meta có ký → Pub/Sub; token refresh khi cần, không có cron | Token đã bị thu hồi vẫn retry mỗi lần dùng |
| Wallet | Apple, Google Wallet | HTTP + APNs / Google API | Header auth và push token vẫn bị ghi log |
| Email của Joy | Mailgun custom domain, SMTP của merchant | Topic sentEmailNotification, không retry | Breaker đầy đủ duy nhất trong Joy, nhưng thử custom domain ở mọi lần gửi (~18k/ngày) |
| Shopify (đường integration) | Webhook đơn hàng, Admin API, Flow | apiHookV2 + Cloud Tasks cho đơn hàng | Enqueue lỗi vẫn trả 200; ~10,7k lần Admin bị throttle/ngày; Flow lỗi vẫn trả 200 |
| API Joy cung cấp | REST v2, webhook gửi merchant, headless, MCP | HTTP function; webhook qua webhookSend, không retry | 2xx không phải JSON bị tính là lỗi; 5xx của merchant không bao giờ retry |
3.3 · Hạ tầng hiện tại có đủ không?
Topic integration để retry:false; queue chung chỉ cho một lần thử
3 app dùng chung integrationRateLimits; cache 30 giây theo instance
unique_id Klaviyo rơi về id ngẫu nhiên; không task nào có tên
Chỉ topic ordered có, gắn bằng script tay, không nằm trong CI
Chỉ SMTP có. 61.240 dòng refresh Klaviyo thất bại
App ghi lỗi bằng text tự do, không bao giờ ghi lần thành công
4 nguồn không ký, 2 fail-open, 1 không xác thực
Token nằm trong payload và log; một khoá hằng trong source
Bằng chứng
Cloud Logging 02/11 → 19/11 (bucket giữ 18 ngày), chỉ đọc, phân trang tới hết. Lỗi số lượng lớn được đếm chính xác.
4.2 · Gom theo nguyên nhân gốc · 336.363 dòng đã đếm
Không tính vào tỷ lệ (khác cửa sổ mẫu): webhook báo lỗi giả 10.491 · fallback custom domain ~18k/ngày · Shopify Admin throttle ~10,7k/ngày · webhook đơn hàng không vào hàng đợi 344.
4.1 · Phát hiện theo từng integration
contact + event bị bỏ sau 429. Retry sleep trong handler rồi return
lần sync profile bị bỏ; hoãn cũng tính vào 3 lần thử. 98% từ đợt 13/11
quyền đã chết vẫn refresh hàng tuần; nhánh invalid_grant không bao giờ chạy tới
invalid_client từ 05/11 trên 8 tài khoản, sau đó vòng lặp TypeError
401/403 trong 10 ngày, dòng nào cũng kèm header auth của merchant
phiên bị thu hồi vẫn retry mỗi lần dùng; không cron, không nhắc kết nối lại
không vào hàng đợi mà vẫn trả 200. Nhét cả ctx.state vào task
gọi inline trong webhook bị throttle; đọc khách trả rỗng, tag bị bỏ
lỗi giả: 2xx kèm body không phải JSON thành 500
thử custom domain cho cả shop chưa xác thực domain
Mục tiêu
Xây một lần, chứng minh trên một app trước (Omnisend event cho phần gửi, Klaviyo cho phần health), rồi từng app chuyển sang sau một cờ bật/tắt.
5.1 · Kiến trúc mục tiêu
5.1b · Mỗi đối tác một kiểu · Joy gửi ra
Phần khác nhau nằm trong adapter của từng app; delivery worker chỉ hỏi adapter "bao giờ được gửi lại" và "có chống trùng không".
| Đối tác | Xác thực | Giới hạn | Khi bận (429) | Chống trùng | Điểm riêng |
|---|---|---|---|---|---|
| Klaviyo | OAuth (hoặc private key) | Theo tài khoản + app, chia theo loại API (event 350/giây, bulk 10/giây) | Header Retry-After | Có: unique_id | Refresh token tối đa 10 lần/phút; bulk không xoá được thuộc tính |
| Omnisend | API key / OAuth | 400/phút cho cả brand, dùng chung với app khác | retryAfter trong body (một số API) | Không chống trùng event automation | Đã chuyển sang API theo ngày, Joy vẫn dùng /v5 |
| Mailchimp | OAuth | 10 kết nối chạy cùng lúc (không tính theo tốc độ) | Không có | Ghi theo email, lặp lại an toàn | Batch không theo thứ tự |
| Attentive | OAuth | Subscribe 10/giây | Header x-ratelimit-* | Chưa rõ | Đăng ký lại người đã đăng ký → khách nhận SMS |
| Gorgias | OAuth | 80 lần / 20 giây | — | — | Joy đang tự giới hạn 35/20 giây trong RAM; hỏng invalid_client từ 05/11 |
| OAuth Meta | — | — | — | Token sống 60 ngày, phải refresh trước khi hết hạn | |
| LINE | Channel token | Quota theo tháng | Không có header | Có: X-Line-Retry-Key (24 giờ) | 429 có thể là hết quota tháng, thử lại vô ích |
| Postscript (mới) | Partner key + key của shop | 15/giây cho mỗi cặp đối tác–shop | Mã lỗi 3002, không header | external_id chưa chắc chống trùng | Tối đa 50 thuộc tính/khách; không bao giờ tự đăng ký khách |
5.1c · Mỗi đối tác một kiểu · đối tác gửi vào Joy
Verifier có một hợp đồng chung, nhưng cách kiểm chữ ký là riêng cho từng nhà cung cấp.
| Nguồn | Cách kiểm thật / giả | Khi Joy trả lỗi | Chống trùng / ghi chú |
|---|---|---|---|
| Shopify webhook | HMAC trên body gốc | Timeout 5 giây; lỗi thì gửi lại 8 lần trong 4 giờ, rồi tự xoá subscription | X-Shopify-Webhook-Id (Joy đang dùng Event-Id) |
| Shopify Flow action | HMAC | Gửi lại tới 36 giờ, kể cả khi timeout hoặc 429 | action_run_id |
| Judge.me | Header JUDGEME-HMAC-SHA256, ký bằng secret app OAuth của Joy | — | — |
| Loox | HMAC, chỉ khi merchant tự đặt key (gói Convert/Unlimited) | — | — |
| Fera | JWT trong URL, ký bằng secret của shop mà Joy đã có | — | Kiểm được ngay |
| Yotpo | Không ký → dùng mã bí mật trong URL | Gửi lại ít nhất 10 lần | WebhookMessageId |
| Stamped | Secret gửi trong header, không ký body | — | — |
| Recharge | X-Recharge-Hmac-Sha256 = SHA-256(secret + body); Joy chưa có secret | Lỗi thì gửi lại rồi xoá webhook | — |
| Loop (mới) | X-Loop-Signature, secret của merchant | Timeout 10 giây; gửi lại 5 lần; có thể nhận hơn một lần | Topic return, trigger return.closed; tự suy ra "đổi hàng" |
Nguồn: tài liệu API chính thức của từng đối tác, đối chiếu ngày 20/11 (verify-partner-api-A/B.md).
5.3 · Bảy nguyên tắc thiết kế
Thêm app mới chỉ cần viết module của app đó, không phải sửa 30 file.
Không chọn: lưu cấu hình app trong database (vẫn phải viết code, lại khó test).
Mỗi lần gửi có mã riêng. Đối tác có chống trùng (Klaviyo, LINE) thì nhận đúng một lần; đối tác không có thì lần không rõ kết quả được giữ lại để kiểm.
Không chọn: bật "thử lại" cho hàng đợi chung (sẽ chạy lại cả trăm việc không liên quan).
Làm lần lượt từng app, bắt đầu từ Klaviyo.
Không chọn: đổi hết một lần trong khi 7 chỗ khác vẫn đang ghi.
Bộ gửi tự lấy token khi chạy, nên việc cũ không chạy nhầm token mới.
Không chọn: chuyển hết token sang Secret Manager ngay (quá lớn, chặn việc khác).
Merchant cấp key cho từng đối tác, và key chỉ mở đúng các API cần dùng.
Không chọn: dùng chung key của shop (mở toàn quyền).
Mỗi app có một công tắc; lỗi thì tắt là quay về cách cũ.
Không chọn: một công tắc cho tất cả, đổi trong một lần.
Không xoá token, không tự ngắt; merchant kết nối lại là chạy tiếp.
Không chọn: tự ngắt và thu hồi quyền như Klaviyo đang làm.
Gửi chắc chắn, không gửi trùng, biết app nào đang hỏng, và mọi thay đổi đều có đường quay lại.
Việc phải làm
5 ngày, trước Black Friday
Klaviyo, Omnisend, Gorgias…
hàng đợi gửi, theo dõi kết nối
Flow, Tapcart, Loop, Postscript
và dọn những thứ đã chết
Chi tiết từng việc (làm gì, ở đâu trong code, thế nào là xong) nằm trong roadmap.md.
Nhóm 1
20/11 → 25/11Nhóm 2
Đợt 1 – 3Sửa thế nào · 1 / 2 · gửi dữ liệu và kết nối
Joy thử lại ngay vài lần trong vài giây rồi bỏ luôn. 205 nghìn lần trong 18 ngày.
Mọi lần gửi đi qua hàng đợi chung. Đối tác bận thì hẹn giờ gửi lại theo luật riêng của từng đối tác, không bỏ. Ngân sách gửi để thấp hơn giới hạn công bố vì quota dùng chung với app khác của merchant.
Không mất dữ liệu; lần gửi không rõ kết quả được giữ lại để kiểm
Một shop hạ hạng hàng loạt sinh ra hàng chục nghìn lần gọi Klaviyo, mỗi khách một lần.
Gom lại thành một job đồng bộ hàng loạt, Klaviyo xử lý một lần.
Hết những đợt nghẽn như ngày 13/11
Klaviyo, Gorgias, Instagram, Mailchimp hết quyền vẫn bị gọi hàng tuần; merchant vẫn thấy "Connected".
Phát hiện mất quyền thì dừng gọi, giữ token, hiện banner cho merchant. Kết nối lại thì tự đồng bộ lại.
Merchant biết và tự sửa được
Mỗi lần mở trang khách hàng, admin hỏi Klaviyo/Omnisend cả khi shop chưa kết nối.
Chỉ hỏi những app shop đã kết nối.
Giảm 80% lỗi Klaviyo trong log
Từ 05/11, refresh token thất bại rồi sinh thêm lỗi khác, ~8.900 dòng/ngày.
Lỗi refresh thì đánh dấu mất kết nối; song song kiểm tra tài khoản OAuth Gorgias của Joy.
Hết vòng lặp, 8 tài khoản được báo
Một shop lỗi làm cả cron dừng; job treo mãi ở trạng thái "đang đồng bộ".
Mỗi shop chạy riêng; job lỗi quá số lần thì đánh dấu thất bại.
Shop khác không bị kéo theo
Sửa thế nào · 2 / 2 · Shopify, webhook, email, bảo mật
Đơn lớn không vào được hàng đợi, nhưng Joy vẫn báo Shopify là "đã nhận". 344 đơn.
Lưu đơn trước rồi mới trả lời Shopify. Hàng đợi chỉ giữ mã đơn nên không còn quá to. Lưu không được thì báo lỗi để Shopify gửi lại.
Không mất đơn nào
Bị Shopify chặn tạm thời thì Joy coi như không có dữ liệu, gắn tag cũng bỏ qua. ~10,7 nghìn lần/ngày.
Bị chặn thì xếp hàng gọi lại sau; gắn tag số lượng lớn thì dùng bulk.
Tag và dữ liệu khách không bị thiếu
Server merchant trả "ok" là Joy tính lỗi; còn lỗi thật thì lại không gửi lại.
Server trả thành công là thành công. Lỗi thật thì tự gửi lại sau.
Hết 10.491 lỗi giả
Log ghi cả key, header, địa chỉ khách, email người nhận.
Log chỉ ghi loại lỗi, mã lỗi và id.
Không còn dòng log lộ secret mới
Bốn app review không ký; Recharge không xác thực. Ai biết URL cũng gửi review giả được.
Mỗi nhà cung cấp một cách: Fera đã ký sẵn (kiểm được ngay); Recharge cần thêm secret của app Recharge; Yotpo không ký được nên dùng mã bí mật trong URL. Có giai đoạn chuyển tiếp để không chặn nhầm.
Chặn review và đơn giả
Flow lỗi vẫn báo thành công; email thử domain riêng của shop chưa có (~18 nghìn lần/ngày); Joy Subscription bỏ qua lần Shopify gửi lại.
Flow báo lỗi rõ; email kiểm domain đã xác thực trước; Joy Subscription lưu xong mới đánh dấu đã xử lý.
Lỗi hiện ra để sửa; bớt 95% nhiễu email
Lỗi tiềm ẩn · từ tài liệu đối tác, log chưa thấy
Tìm ra khi đối chiếu cách sửa với tài liệu API chính thức của từng đối tác. Mỗi thẻ: chuyện gì có thể xảy ra → làm gì.
Nếu handler của Joy trả mã khác 2xx, Recharge sẽ gửi lại rồi xoá webhook. Joy chưa lưu secret để kiểm chữ ký Recharge.
Kiểm mã trả về trên staging; chọn cách lấy secret (xin shop hay mã trong URL) khi làm verifier.
Mỗi lần đồng bộ hàng loạt gọi subscribe cho cả người đã đăng ký, Attentive nhắn SMS cho họ.
Chỉ gọi subscribe cho khách đã đồng ý và chưa đăng ký; giới hạn 10 lần/giây.
/v5Joy vẫn gọi /v5; Omnisend chuyển sang API theo ngày (2026-03-15), chưa báo ngày tắt.
Adapter mới viết theo API mới; hỏi Omnisend ngày tắt /v5.
Gửi lại một event có thể làm automation của merchant chạy 2 lần.
Lần gửi không rõ kết quả được giữ lại để kiểm, không tự gửi lại.
Khách mới được thêm vào list ở trạng thái "subscribed" mà không kiểm consent.
Kiểm lại cùng lúc với việc sửa consent của Attentive.
Shopify khuyên dùng X-Shopify-Webhook-Id; Joy đang dùng X-Shopify-Event-Id cho mọi topic.
Đổi khoá chống trùng khi làm webhook đơn hàng.
Joy refresh mỗi lần gặp 401, không khoá; 429 từ endpoint token dễ bị hiểu nhầm là mất quyền.
Refresh tuần tự theo shop; 429 ở endpoint token là lỗi tạm, không đánh dấu mất kết nối.
Có batch lưu lại nhưng không ai xử lý.
Winn xác nhận; còn dùng thì xử lý nốt, không thì gỡ code.
Loop không có trường "khách chọn đổi hàng"; Postscript không ghi rõ có chống trùng theo external_id.
Thử trên dữ liệu thật / shop test trong spike trước khi làm.
Nhóm 3
làm thử trên một app trướcMọi app gửi qua một chỗ. Đối tác bận thì tự gửi lại, không gửi trùng, không âm thầm bỏ. Làm thử Omnisend trước.
Biết app nào đang tốt, chập chờn hay mất kết nối. Mất kết nối thì dừng gọi, giữ token. Làm Klaviyo trước.
Banner kiểu "Klaviyo mất kết nối, email sinh nhật đang dừng", kèm nút kết nối lại và đồng bộ lại.
Chỉ nhận dữ liệu thật, từ đúng đối tác, cho đúng shop.
Thao tác lớn chạy thành một job, không thành hàng chục nghìn lần gọi.
Xem shop gửi lỗi những gì và bấm gửi lại.
Mỗi app khai báo ở một chỗ, có test bắt lỗi khi quên sửa chỗ nào.
Tỷ lệ thành công của từng app, có cảnh báo khi tụt.
Nhóm 4
App mớiOkendo, REVIEWS.io, Junip, Growave. Làm nhanh, Rivo cũng làm theo cách này.
5/9 đối thủ đã có. Phải sửa lỗi lộ key trước khi làm tiếp.
Lên listing trước. Điểm mạnh: chưa đối thủ nào cộng điểm khi khách chọn đổi hàng thay vì hoàn tiền.
Ưu tiên số một, 6/9 đối thủ đã có. Cần hàng đợi gửi chung xong trước để không gửi trùng SMS.
Skio, Loop Subscriptions, Stay AI: sáu app loyalty khác đã có mặt, Joy thì chưa.
Nhóm 5
API cho đối tác & dọn dẹpMerchant tạo key riêng cho từng đối tác. Key chỉ mở đúng phần cần: khách hàng, xem hạng, xem phần thưởng, cộng/trừ điểm. Mỗi đối tác có giới hạn lượt gọi riêng và thu hồi được bất cứ lúc nào. Loop, Tapcart, Okendo sẽ dùng API này.
Cần chốt trước 25/11 đối tác dùng API trên gói nào
7 · Thứ tự và mốc thời gian
Nghỉ Tết 04/02 → 10/02. Thay đổi lớn chỉ bắt đầu từ tuần 04/01.
7.2 · An toàn khi bật thay đổi
| Thay đổi | Phải theo dõi được | Khi nào quay lại | Quay lại bằng cách |
|---|---|---|---|
| Các sửa nhỏ đầu tiên | Cảnh báo dữ liệu bị bỏ và lỗi Klaviyo | Có lỗi lạ mới xuất hiện | Deploy lại bản cũ, dưới 30 phút |
| Hàng đợi gửi chung, từng app | Số gửi thành công / thử lại / lỗi của từng app; có gửi trùng không | Thành công thấp hơn cách cũ, hoặc có gửi trùng | Tắt công tắc của app đó, dưới 15 phút |
| Báo "mất kết nối" | Bao nhiêu shop bị báo nhầm | Báo nhầm vượt ngưỡng | Tắt công tắc, chạy script trả trạng thái cũ |
| Webhook đơn hàng trả lỗi thật | Một tuần chạy thử chỉ ghi nhận | Lỗi tăng hơn lúc chạy thử | Deploy lại bản cũ, đăng ký lại webhook |
| Bắt buộc kiểm chữ ký | Shop nào còn gửi không ký | Chặn nhầm dữ liệu thật | Bật lại chế độ chấp nhận cả hai |
| Mã hoá lại SMTP, đổi key Tapcart | Lỗi giải mã, lỗi gửi email, danh sách shop | Lỗi tăng đột biến | Vẫn đọc được bản cũ; đổi từng shop một |
Thay đổi nào merchant nhìn thấy cũng có sẵn bài hướng dẫn, mẫu trả lời cho support và một dòng giải thích trong app.
8 · Cần anh/Winn quyết
Tuyển, mượn một dev 8–10 tuần, hay tạm chỉ làm phần sửa lỗi. Trước 02/12 · chặn Flow, Loop, Postscript, F1
Free có được dùng không, có tính vào quota của merchant không. Winn + product · 25/11 · chặn F1, Loop, Tapcart
Tài khoản OAuth của Joy bên Gorgias còn dùng được không; thử refresh một tài khoản đang tốt. Trước 25/11
Chấp nhận báo nhầm bao nhiêu; có tự ngắt không; merchant có thấy "chập chờn" không. Trước 04/01
Chấp nhận trùng, chấp nhận thiếu, hay người kiểm tay; giữ lại tối đa bao lâu cho từng đối tác. Tạm thời Omnisend event mặc định giữ lại để kiểm. Trước Đợt 2 · chặn Postscript
9 · Rủi ro
Chạy một tuần chỉ ghi nhận trước; không xoá token nên báo nhầm cũng không hỏng gì
Mỗi lần gửi có mã riêng; lần nào không rõ thì giữ lại cho người kiểm
Nếu đúng, đồng bộ hàng loạt sẽ nhân thiệt hại → chưa có kết quả thử thì chưa chạy
Làm hỏng block cũ → đổi từng shop, sau khi block mới đã chạy
Trước khi gửi luôn kiểm khách còn được phép gửi không
Chỉ ghi mẫu, có ngân sách, để riêng một bucket
Test lỗi sai lý do → chuẩn bị queue/index trên staging trước
Lỗi trước đây im lặng nay hiện ra → so sánh có tính phần này
Không có người; đối tác duyệt chậm; Chatty cập nhật chậm
Cắt bớt phạm vi, không bao giờ bỏ bước an toàn
5 ngày tới
Nguồn: roadmap.md v7 và integration-usage-counts.md, plans/261119-2330-integrations-roadmap.