Webhook cho phép Sellfern thông báo cho các hệ thống bên ngoài của bạn theo thời gian thực khi các sự kiện xảy ra — đơn hàng mới, thay đổi trạng thái, cập nhật hoàn tất đơn, chi phí và nhiều hơn nữa. Thay vì polling API, bạn đăng ký một điểm cuối HTTPS và Sellfern gửi một yêu cầu POST đã ký vào lúc một sự kiện xảy ra.Documentation Index
Fetch the complete documentation index at: https://docs.sellfern.com/llms.txt
Use this file to discover all available pages before exploring further.
Các sự kiện có sẵn
Sellfern phát ra các sự kiện sau. Bạn có thể đăng ký bất kỳ tổ hợp nào khi đăng ký một điểm cuối webhook.| Sự kiện | Mô tả |
|---|---|
order.created | Một đơn hàng mới đã được tạo trong Sellfern |
order.updated | Một hoặc nhiều trường trên một đơn hàng đã được cập nhật |
order.status_changed | Trạng thái của một đơn hàng đã chuyển (ví dụ: New → Shipped) |
order.fulfillment.shipped | Một bản hoàn tất đơn cho một đơn hàng đã được đánh dấu là đã vận chuyển |
order.fulfillment.delivered | Một bản hoàn tất đơn đã được xác nhận là đã giao |
expense.created | Một bản ghi chi phí mới đã được thêm |
ticket.created | Một ticket hỗ trợ mới đã được mở |
ticket.updated | Một ticket hiện có đã được cập nhật |
Tạo một điểm cuối webhook
Qua bảng điều khiển
Trong Sellfern, vào Settings → Webhooks và nhấp New endpoint. Dán URL HTTPS của bạn, chọn các sự kiện bạn muốn nhận và lưu. Sellfern tạo ra một bí mật điểm cuối mà bạn có thể dùng để xác minh các payload đến.Qua API
Gửi một yêu cầuPOST tới /api/v2/webhooks với một url và một mảng events. Token của bạn phải có phạm vi webhooks:manage.
id và secret được tạo mà bạn nên lưu trữ an toàn.
Tất cả các điểm cuối quản lý webhook yêu cầu một token với phạm vi
webhooks:manage. Tạo hoặc xoay vòng token trong Settings → API Tokens.Cấu trúc payload webhook
Sellfern gửi một yêu cầuPOST tới điểm cuối của bạn với body JSON. Yêu cầu bao gồm hai tiêu đề:
X-Sellfern-Event— tên sự kiện (ví dụ:order.status_changed)X-Sellfern-Signature— một HMAC-SHA256 hex digest của body yêu cầu thô, được ký bằng bí mật điểm cuối của bạn
order.status_changed:
X-Sellfern-Signature. Luôn sử dụng so sánh thời gian không đổi để ngăn các cuộc tấn công thời gian:
Quản lý điểm cuối webhook
| Phương thức | Đường dẫn | Mô tả |
|---|---|---|
GET | /api/v2/webhooks | Liệt kê tất cả các điểm cuối đã đăng ký cho tổ chức của bạn |
PATCH | /api/v2/webhooks/:id | Cập nhật URL, sự kiện hoặc trạng thái bật của một điểm cuối |
DELETE | /api/v2/webhooks/:id | Xóa một điểm cuối (truyền ?confirm=<id> trong chuỗi truy vấn) |
POST | /api/v2/webhooks/:id/test | Gửi một sự kiện thử nghiệm tới điểm cuối |
GET | /api/v2/webhooks/:id/deliveries | Lấy các lần giao gần đây và phản hồi của chúng |
Ví dụ: Bot theo dõi đơn hàng Discord
Sellfern đi kèm một ví dụ máy chủ Express sẵn sàng triển khai lắng nghe các sự kiệnorder.status_changed và đăng một embed có định dạng lên một kênh Discord.
Đây là mẫu xử lý cốt lõi:
Xử lý sự cố
Sellfern không gọi điểm cuối của tôi
Sellfern không gọi điểm cuối của tôi
Kiểm tra rằng URL của bạn có thể tiếp cận công khai qua HTTPS. Sellfern sẽ không gửi tới
localhost hoặc chứng chỉ tự ký. Sử dụng công cụ tunneling như ngrok trong quá trình phát triển và đảm bảo điểm cuối trả về mã trạng thái 2xx trong cửa sổ thời gian chờ.Việc giao đang hết thời gian chờ
Việc giao đang hết thời gian chờ
Sellfern mong đợi điểm cuối của bạn phản hồi trong vòng 10 giây. Nếu handler của bạn thực hiện công việc nặng, hãy xác nhận webhook ngay lập tức với phản hồi 200 và xử lý payload bất đồng bộ (ví dụ, đẩy nó vào một hàng đợi).
Việc giao thất bại và thử lại
Việc giao thất bại và thử lại
Nếu điểm cuối của bạn trả về trạng thái không phải 2xx hoặc hết thời gian, Sellfern thử giao lại với backoff theo cấp số nhân. Bạn có thể kiểm tra các lần giao gần đây và mã phản hồi của chúng trong bảng điều khiển dưới Settings → Webhooks → Deliveries, hoặc qua
GET /api/v2/webhooks/:id/deliveries.Xác minh chữ ký đang thất bại
Xác minh chữ ký đang thất bại
Đảm bảo bạn đang tính HMAC trên body yêu cầu thô trước bất kỳ phân tích JSON nào. Nhiều framework phân tích body trước khi handler của bạn chạy — bạn phải bắt các byte thô riêng (xem tùy chọn
verify trong middleware express.json() của Express).