Trang chủ › Blog › Webhook Shopify Cơ Bản: Hướng Dẫn Thiết Yếu Cho Lập Trình Viên

Webhook Shopify Cơ Bản: Hướng Dẫn Thiết Yếu Cho Lập Trình Viên

Nắm vững webhook Shopify từ gốc: các event topic, cơ chế gửi, cách xác thực và best practice để xây dựng tích hợp ecommerce đáng tin cậy.

Cập nhật 2026-06-20

Nếu bạn đang xây app hay tích hợp cho các cửa hàng Shopify, webhook là một trong những công cụ mạnh nhất — nhưng cũng dễ bị hiểu sai nhất — mà bạn có trong tay. Thay vì liên tục gọi (polling) Shopify API để hỏi "có gì thay đổi chưa?", webhook cho phép Shopify chủ động báo cho ứng dụng của bạn ngay khoảnh khắc có sự kiện quan trọng xảy ra. Trong bài này, chúng ta sẽ tìm hiểu webhook là gì, hoạt động ra sao, và các bước thực tế để dùng chúng một cách đáng tin cậy.

Webhook Shopify Là Gì?

Webhook là cách để Shopify đẩy thông báo real-time đến ứng dụng của bạn mỗi khi có sự kiện cụ thể xảy ra trong cửa hàng của một nhà bán. Khi bạn đăng ký một webhook topic — ví dụ orders/create — Shopify sẽ gửi một HTTP POST request đến endpoint của bạn mỗi lần có đơn hàng mới được tạo. Ứng dụng của bạn sau đó xử lý thông báo đó: đồng bộ đơn hàng vào database, kích hoạt một quy trình, hay báo cho nhân viên.

Cách này khác hẳn với polling — vốn lãng phí lượt gọi API và thường gây ra độ trễ. Webhook hoạt động theo hướng sự kiện (event-driven), nên rất lý tưởng để xây dựng các tích hợp phản hồi nhanh và dễ mở rộng.

Các Webhook Topic Thường Gặp

Shopify cung cấp webhook cho toàn bộ vòng đời của cửa hàng. Dưới đây là những topic được dùng nhiều nhất:

Đơn hàng & Giao dịch

orders/create, orders/update, orders/cancelled, orders/fulfilled – Theo dõi việc tạo đơn, thay đổi, hủy đơn và trạng thái hoàn tất đơn (fulfillment)
order_transactions/create – Kích hoạt khi có khoản thanh toán hoặc hoàn tiền được thêm vào đơn hàng

Khách hàng

customers/create, customers/update, customers/delete – Theo dõi thay đổi hồ sơ khách hàng
customers/disable, customers/enable – Ghi nhận việc kích hoạt và vô hiệu hóa tài khoản
customers/merge – Kích hoạt khi hai hồ sơ khách hàng được gộp lại

Sản phẩm & Bộ sưu tập

products/create, products/update, products/delete – Theo dõi thay đổi tồn kho và metadata sản phẩm
collections/create, collections/update, collections/delete – Theo dõi cập nhật bộ sưu tập
product_listings/add, product_listings/update, product_listings/remove – Theo dõi việc đăng bán sản phẩm trên nhiều kênh

Hoàn tất đơn (Fulfillment)

fulfillments/create, fulfillments/update – Theo dõi trạng thái vận chuyển
fulfillment_orders/ (nhiều topic) – Các chuyển trạng thái chi tiết của fulfillment order

Tuân thủ pháp lý

customers/data_request, customers/redact, shop/redact – Các webhook bắt buộc liên quan đến quyền riêng tư, phục vụ GDPR và các quy định tương tự

Cơ Chế Gửi Webhook Hoạt Động Như Thế Nào

Khi đăng ký một webhook subscription, bạn cần chỉ định:

Topic – Sự kiện nào cần theo dõi (ví dụ orders/create)
Đích đến (Destination) – Nơi Shopify gửi thông báo tới (một URL HTTPS, một Google Pub/Sub URI, hoặc một Amazon EventBridge ARN)
Định dạng (Format) – JSON hoặc XML (JSON là mặc định và được khuyến nghị)
Bộ lọc (Filters) (tùy chọn) – Thu hẹp những lượt gửi nào sẽ kích hoạt (ví dụ chỉ với một loại sản phẩm cụ thể)

Sau khi cấu hình xong, đây là những gì diễn ra:

Một sự kiện xảy ra trong cửa hàng (ví dụ khách đặt một đơn hàng)
Shopify tạo một payload JSON chứa chi tiết sự kiện và gửi một HTTP POST đến endpoint của bạn
Endpoint của bạn nhận request và trả về mã trạng thái HTTP 2xx trong vòng 5 giây
Nếu bạn trả về 2xx, lượt gửi được đánh dấu là thành công
Nếu Shopify không nhận được phản hồi (timeout, lỗi 5xx, hoặc lỗi mạng), nó sẽ thử lại tối đa 8 lần trong vòng 4 giờ theo cơ chế exponential backoff

Cơ chế thử lại này đảm bảo bạn không bỏ sót sự kiện, nhưng cũng đồng nghĩa endpoint của bạn phải có tính idempotent — tức là phải xử lý được việc nhận cùng một sự kiện nhiều lần mà không tạo ra bản ghi trùng.

Xác Thực Webhook Thật Sự Đến Từ Shopify

Mỗi lượt gửi webhook đều kèm theo các header bảo mật để chứng minh nó đến từ Shopify:

X-Shopify-Hmac-SHA256 – Một chữ ký HMAC được tính bằng secret key của app
X-Shopify-Webhook-Id – Mã định danh duy nhất cho lượt gửi này
X-Shopify-Topic – Topic đã kích hoạt lượt gửi
X-Shopify-Triggered-At – Dấu thời gian theo chuẩn ISO 8601 lúc sự kiện xảy ra

Để xác thực, hãy giải mã header X-Shopify-Hmac-SHA256 và so sánh nó với một hash HMAC-SHA256 tính từ phần thân (raw body) của request, dùng API secret của app. Nếu hai giá trị khớp nhau, nghĩa là webhook thật sự đến từ Shopify. Cách này ngăn chặn các request giả mạo từ kẻ xấu.

Ngoài ra, hãy dùng X-Shopify-Webhook-Id để theo dõi những lượt gửi bạn đã xử lý. Nếu nhận được cùng một Webhook-Id hai lần, hãy bỏ qua bản trùng — điều này xử lý đúng tình huống Shopify thử lại nhưng phản hồi đầu tiên của bạn chỉ bị trễ chứ không hề mất.

Best Practice Để Webhook Đáng Tin Cậy

1. Đừng chỉ dựa vào mỗi webhook. Shopify không cam kết gửi được 100% mọi sự kiện webhook. Nếu cửa hàng của nhà bán bị throttle nặng, hoặc Shopify gặp sự cố ngay trong khung thời gian thử lại, bạn có thể bỏ lỡ một sự kiện. Hãy triển khai một tác vụ đối soát (reconciliation job) định kỳ gọi Shopify API để lấy về các thay đổi gần đây (dùng bộ lọc updated_at) và đồng bộ lại bất cứ thứ gì bị sót.

2. Đừng giả định webhook đến đúng thứ tự. Webhook của các topic khác nhau có thể không đến theo trình tự thời gian. Nếu products/update đến trước orders/create cho cùng một đơn, hãy dùng dấu thời gian (header X-Shopify-Triggered-At hoặc trường updated_at trong payload) để dựng lại đúng trình tự.

3. Giữ endpoint nhanh và xử lý bất đồng bộ. Shopify áp giới hạn timeout 5 giây. Nếu việc xử lý chậm, hãy đẩy phần nặng sang một hàng đợi tác vụ nền (Redis, RabbitMQ, v.v.) và trả về 2xx ngay lập tức.

4. Dùng bộ lọc gửi để giảm nhiễu. Nếu bạn chỉ quan tâm đến các đơn trên một mức giá trị nhất định, hoặc sản phẩm trong một bộ sưu tập cụ thể, hãy dùng tham số filter khi đăng ký. Điều này giúp giảm dung lượng payload và tiết kiệm sức xử lý.

5. Ghi log mọi thứ. Lưu lại payload webhook, dấu thời gian và kết quả xử lý. Khi gỡ lỗi các vấn đề tích hợp, những log này là vô giá.

Thiết Lập Một Webhook (Ví Dụ Nhanh)

Trong một app Node.js hoặc Python điển hình dùng Shopify CLI hoặc Admin API:

Đăng ký webhook subscription trong shopify.app.toml hoặc qua GraphQL Admin API, kèm topic và endpoint HTTPS của bạn
Endpoint của bạn nhận một POST request chứa payload sự kiện
Xác thực chữ ký HMAC
Trích xuất dữ liệu cần thiết và xử lý (đồng bộ vào database, kích hoạt quy trình, v.v.)
Trả về mã trạng thái 2xx để xác nhận đã nhận
Nếu xử lý thất bại, trả về mã khác 2xx để Shopify thử lại

Với những nhà bán đang vận hành nhiều cửa hàng Shopify cùng lúc, webhook càng trở nên thiết yếu — bạn cần thông báo hợp nhất từ tất cả cửa hàng để có thể hành động ngay theo thời gian thực. Đây chính là lúc các công cụ tập trung — gom webhook từ mọi cửa hàng (kèm tự động đồng bộ đơn hàng và dashboard real-time) — giúp đơn giản hóa vận hành một cách rõ rệt.

Vì Sao Webhook Quan Trọng Với Vận Hành Đa Cửa Hàng

Nếu bạn đang quản lý webhook trên nhiều cửa hàng, hoặc xây công cụ cho những nhà bán làm việc đó, webhook mở ra hàng loạt tự động hóa mạnh mẽ: đồng bộ đơn hàng sang hệ thống fulfillment, kích hoạt chiến dịch email, cập nhật tồn kho, hay đánh dấu các đơn giá trị cao để duyệt thủ công. Không có webhook, bạn sẽ kẹt lại với polling — vừa hao quota API vừa gây độ trễ.

Sẵn sàng làm chủ vận hành Shopify của mình? Nền tảng StoreFleet hợp nhất webhook và dữ liệu từ tất cả cửa hàng của bạn vào một dashboard duy nhất, tích hợp sẵn theo dõi đơn hàng real-time, cập nhật vận đơn hàng loạt qua 17TRACK, và báo cáo tài chính hợp nhất. Dù bạn đang chạy 5 hay 50 cửa hàng, một tích hợp duy nhất thay thế cho hàng chục luồng công việc rời rạc. Đăng ký buổi demo 1-1 miễn phí, thiết kế riêng cho cửa hàng của bạn tại https://storefleet.io.vn.