POST tới địa chỉ cửa hàng đăng ký, kèm chữ ký theo chuẩn Standard Webhooks để hệ thống của bạn kiểm tra tin đúng là do chúng tôi gửi.
Bật tính năng và phân quyền
- Tính năng Webhook không bật sẵn. Liên hệ bộ phận hỗ trợ để bật cho cửa hàng. Cửa hàng chưa được bật thì mục Webhook không hiện, kể cả với chủ cửa hàng.
- Quyền Webhook (Xem) cho xem địa chỉ nhận và nhật ký gửi. Quyền Webhook (Quản lý) cho thêm, sửa, xoá địa chỉ, đổi khoá bí mật, gửi thử và gửi lại tin.
- Webhook nhận toàn bộ nội dung của sự kiện, trong đó có nội dung chuyển khoản do người chuyển nhập. Vì vậy bạn chỉ chọn được những sự kiện mà chính bạn có quyền xem: sự kiện về giao dịch và tài khoản nhận tiền (
payment.*) cần quyền xem Nhận tiền. Quyền này được kiểm lại ở mọi thao tác ghi: thêm, sửa (kể cả chỉ đổi địa chỉ), đổi khoá, bật lại, gửi thử, gửi lại.
Thêm một địa chỉ nhận
Vào Nhà phát triển › Webhook › Thêm webhook, nhập:
Mỗi cửa hàng có tối đa 5 địa chỉ, tính cả địa chỉ đang tắt; xoá địa chỉ không còn dùng để thêm địa chỉ mới. Địa chỉ webhook thường chứa mã bí mật trong đường dẫn hoặc query; hệ thống chỉ ghi tên miền vào nhật ký hoạt động và log lỗi.
Cùng lúc đó, một tin thử
test.ping được xếp hàng gửi tới địa chỉ mới. Kết quả hiện ở tab Nhật ký gửi và không chặn việc tạo.
Nút Gửi thử ở mỗi địa chỉ gửi thêm một tin test.ping bất cứ lúc nào: tối đa 3 tin thử đang chờ cùng lúc và 10 tin thử mỗi giờ cho mỗi địa chỉ, tính cả tin thử lúc tạo.
Đổi khoá bí mật
Đổi khoá bí mật (menu của mỗi địa chỉ) tạo khoá mới, hiện một lần. Khoá cũ vẫn dùng được 24 giờ: trong thời gian đó mỗi tin mang cả hai chữ ký trongwebhook-signature, cách nhau một dấu cách, và thư viện Standard Webhooks chấp nhận tin nếu một trong hai khớp. Hãy cập nhật khoá mới vào hệ thống của bạn trong 24 giờ. Đổi khoá lần nữa trong thời gian đó thì khoá cũ nhất hết hiệu lực.
Nên đổi khoá khi nghi khoá bị lộ, khi người giữ khoá nghỉ việc, hoặc định kỳ.
Webhook tự động tắt
Webhook do hệ thống tự tắt hiện một thông báo ở đầu danh sách, gọi bằng mô tả và địa chỉ, kèm lý do và nút Bật lại. Webhook bạn tự tắt (mục Tắt ở menu ••• của dòng) ghi “Đã tắt” ở cột Trạng thái, và bạn bật lại ở chính menu đó.
Mỗi tin chỉ được thử trong khoảng 3 ngày, nên chỉ webhook vẫn tiếp tục nhận sự kiện mới mới chạm mốc 5 ngày. Một webhook lỗi một lần rồi không có sự kiện nào nữa thì vẫn giữ nguyên bật.
Khi webhook tắt (do bạn hay do hệ thống), sự kiện xảy ra trong lúc đó được giữ 72 giờ ở trạng thái Tạm giữ. Bật lại trong 72 giờ thì chúng được gửi bù; quá 72 giờ thì bị huỷ. Bật lại cũng xoá dấu “đang lỗi liên tục” của địa chỉ. Hãy sửa lỗi ở hệ thống của bạn trước khi bật lại.
Khi hệ thống tự tắt một webhook, chủ cửa hàng nhận email báo kèm thời hạn giữ sự kiện, nếu tài khoản của chủ cửa hàng có email.
Bộ phận hỗ trợ có thể bật lại giúp một webhook do hệ thống tự tắt, không bật lại webhook bạn tự tắt. Việc này hiện trong nhật ký hoạt động của cửa hàng là “Bộ phận hỗ trợ bật lại webhook”.