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: New 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ó mười một 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
course.enrolled	Một học viên được cấp quyền học
course.revoked	Quyền học bị thu hồi
form.submitted	Một lượt gửi biểu mẫu được lưu lại

form.submitted phát cho mọi lượt gửi đã lưu của mọi biểu mẫu trên site — liên hệ, đặt hàng, đặt lịch — không bao giờ cho một lượt bị từ chối. Payload đầy đủ và cách nó nối với hành động trong trình dựng nằm ở Hành động của biểu mẫu.

Hai sự kiện áp chót thuộc Ứng dụng Khoá học, và đi thành cặp là cố ý: một tích hợp chỉ nghe cấp quyền sẽ giữ mãi một học viên đã hoàn tiền trong hệ thống học của bạn, và nó không cách nào hỏi ra "sự vắng mặt" của một thứ.

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 sau khi lưu — và chỉ cho người có quyền sửa

"Chuỗi bí mật ký chỉ hiện ra sau khi bạn lưu." Cần lại sau đó thì mở menu của điểm nhận: Xem lại chuỗi bí mật ký đưa ra đúng chuỗi cũ, Đổi chuỗi bí mật ký tạo chuỗi mới — và "chuỗi bí mật hiện tại sẽ ngừng hoạt động ngay lập tức", nên đổi xong phải cập nhật bên nhận trước khi sự kiện kế tiếp tới.

Cả ba đường — lúc tạo, xem lại, đổi — đều đòi quyền sửa webhook. Danh sách và trang chi tiết không bao giờ mang chuỗi bí mật, kể cả một ô rỗng, vì webhooks.read với tới cả vai trò thấp nhất trên một cửa hàng — và một người chỉ được xem mà đọc được khoá ký thì giả mạo được 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 — đượ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 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, 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. Cần trình tự thì đọ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. Hết bảy lần, lần gửi đó vào trạng thái Đã bỏ.

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; mỗi lần là Đang chờ, Đã gửi hay Đã bỏ. 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ịch sử gửi không bao giờ chứa payload. Cần biết chính xác cái gì đã được gửi thì cái phong bì 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 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 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.

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

Chỉ xem

Vai trò của bạn chỉ có webhooks.read thì 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 X-WB-Signature, cùng X-WB-Timestamp, X-WB-Event-Id, X-WB-Event-Type và X-WB-Attempt. 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.