Webhook

Quản lý → Cài đặt → Webhook (en: Manage → Settings → Webhooks).

"Đăng ký một URL để nhận sự kiện ngay khi chúng xảy ra, thay vì phải liên tục hỏi lại API."

Đây là lý do một cửa hàng với tới được qua API thay vì bằng một vòng lặp hỏi liên tục. Một agency vận hành năm mươi cửa hàng đăng ký năm mươi lần bằng năm mươi lời gọi, thay vì bấm qua năm mươi màn hình cài đặt.

Thêm một điểm nhận

Thêm điểm nhận (en: Add endpoint).

URL điểm nhận — địa chỉ hệ thống của bạn, ví dụ https://example.com/hooks/web-builder.

Mô tả — nhãn nội bộ, ví dụ "Đồng bộ đơn hàng sang hệ thống kho".

Sự kiện — chọn ít nhất một. Có tám loại:

Sự kiện	Kích hoạt khi
order.created	Một đơn hàng được đặt
order.updated	Trạng thái, thanh toán hoặc giao hàng của một đơn thay đổi
customer.created	Một khách hàng được thêm
customer.updated	Một hồ sơ khách hàng thay đổi
product.created	Một sản phẩm được tạo
product.updated	Một sản phẩm thay đổi
product.deleted	Một sản phẩm bị gỡ
page.published	Một trang lên sóng

Bật — công tắc.

Một điểm nhận không đăng ký sự kiện nào sẽ không bao giờ kích hoạt, mà cũng chẳng có lỗi nào để bạn nhận ra — nên biểu mẫu bắt buộc chọn ít nhất một.

Ba điều sẽ làm bạn bất ngờ

1. Chuỗi bí mật ký chỉ hiện đúng một lần

"Chuỗi bí mật ký chỉ hiện ra sau khi bạn lưu." Và chỉ lần đó.

Không có route nào đọc lại nó — GET, danh sách và cập nhật đều trả về điểm nhận mà hoàn toàn không có trường bí mật, kể cả một trường rỗng. Mất nó thì cách sửa là xoá điểm nhận và đăng ký cái mới.

Lý do ngặt nghèo vậy: quyền webhooks.read cấp riêng được và với tới cả vai trò thấp nhất trên một cửa hàng. Một lệnh GET trả về được khoá ký sẽ cho phép vai trò đó giả mạo các lần gửi vào chính hệ thống của bạn.

2. Trùng lặp sẽ xảy ra

Việc gửi là ít nhất một lần, không bao giờ đúng một lần. Một lần gửi mà nền tảng tin là thất bại — timeout, đứt kết nối, một mã 5xx — sẽ được gửi lại toàn bộ, kể cả khi hệ thống của bạn đã xử lý xong và chỉ có phản hồi quay về là bị mất.

Nếu bên nhận của bạn biến thẳng order.created thành một lần tính tiền, một email, hay một lần trừ kho mà không kiểm gì trước, thì sớm muộn nó sẽ làm việc đó hai lần.

Cách chống: mỗi lần gửi mang một id giữ nguyên qua mọi lần thử (cũng là header X-WB-Event-Id). Ghi lại những id đã xử lý, và cho một lần lặp lại đi qua mà không làm gì.

3. Không có thứ tự

Các lần gửi đi ra theo thứ tự chúng đến hạn, không phải theo thứ tự sự kiện đã xảy ra. Một lần thử lại nằm chờ sau khoảng lùi của nó, nên một sự kiện mới hơn của cùng tài nguyên có thể tới trước.

Đừng suy ra trình tự từ thứ tự nhận. Nếu bạn cần trình tự, hãy đọc updatedAt của chính tài nguyên đó.

Trạng thái

Trạng thái	Nghĩa là
Đang hoạt động	Bình thường
Đã tắt	Bạn đã tắt công tắc
Đang lỗi	Ba lần gửi thất bại liên tiếp

Đang lỗi không có nghĩa là hỏng hẳn: "Vẫn đang thử lại — chỉ cần một lần thành công là hết trạng thái này."

Lịch thử lại có bảy lần, trải khoảng 32,6 giờ: ngay lập tức, +1 phút, +5 phút, +30 phút, +2 giờ, +6 giờ, +24 giờ. Đủ dài để sống qua một lần deploy, một chứng chỉ hết hạn hay một đêm sự cố; đủ ngắn để tuần sau không còn gì đang được thử lại.

Một điểm nhận không bị tắt vì chuyện này — nó vẫn nhận sự kiện mới, bởi một tích hợp tự quay lại được thì nên tự bắt kịp, chứ không nên bị âm thầm tắt đi.

Kiểm tra xem nó có chạy không

Gửi sự kiện thử (en: Send test event) bắn một lần gửi thật vào URL của bạn.

Xem lịch sử gửi (en: View deliveries) hiện các lần thử gần nhất kèm mã trạng thái và lỗi. Cột Lần thành công gần nhất trong danh sách trả lời nhanh câu "nó còn sống không".

Lưu ý: lịch sử gửi không bao giờ chứa payload. Nếu bạn cần biết chính xác cái gì đã được gửi, thì cái phong bì mà bên nhận của bạn đã nhận chính là nó.

URL bị chặn

Một URL trỏ vào địa chỉ nội bộ, loopback hay link-local sẽ bị từ chối ngay với 400 blocked_url. Địa chỉ còn được kiểm lại một lần nữa vào lúc mở kết nối, vì câu trả lời DNS của một tên miền có thể đổi sau lần kiểm đầu — và chuyển hướng thì không bao giờ được đi theo.

Bạn không phải gỡ rối gì cả: câu trả lời tới ngay lập tức.

Chỉ xem

Nếu vai trò của bạn chỉ có webhooks.read, màn hình nói rõ: "Bạn có thể xem các điểm nhận đã đăng ký, nhưng không thể tạo hoặc thay đổi."

Xác minh chữ ký

Mỗi lần gửi mang header X-WB-Signature. Cách kiểm — kể cả chi tiết dễ sai nhất (chuỗi được ký dùng giây Unix, không phải giá trị RFC3339 trong header) — nằm ở API công khai.