Chuyển đến nội dung chính

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.

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.

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ệnMô tả
order.createdMột đơn hàng mới đã được tạo trong Sellfern
order.updatedMột hoặc nhiều trường trên một đơn hàng đã được cập nhật
order.status_changedTrạng thái của một đơn hàng đã chuyển (ví dụ: New → Shipped)
order.fulfillment.shippedMộ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.deliveredMột bản hoàn tất đơn đã được xác nhận là đã giao
expense.createdMột bản ghi chi phí mới đã được thêm
ticket.createdMột ticket hỗ trợ mới đã được mở
ticket.updatedMộ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ầu POST 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.
curl -X POST "https://api.sellfern.com/api/v2/webhooks" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/sellfern",
    "events": ["order.created", "order.status_changed"]
  }'
Phản hồi thành công trả về HTTP 201 với đối tượng điểm cuối mới, bao gồm một idsecret đượ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ầu POST 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
Đây là một payload ví dụ cho order.status_changed:
{
  "event": "order.status_changed",
  "order_id": 10482,
  "old_status": "In Production",
  "new_status": "Shipped",
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "occurred_at": "2026-05-22T09:14:32Z"
}
Xác minh chữ ký Tính HMAC-SHA256 của body yêu cầu thô bằng bí mật điểm cuối của bạn và so sánh với 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:
const crypto = require('crypto');

function verifySignature(req, secret) {
  const signature = req.headers['x-sellfern-signature'];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Quản lý điểm cuối webhook

Phương thứcĐường dẫnMô tả
GET/api/v2/webhooksLiệ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/:idCậ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/:idXóa một điểm cuối (truyền ?confirm=<id> trong chuỗi truy vấn)
POST/api/v2/webhooks/:id/testGửi một sự kiện thử nghiệm tới điểm cuối
GET/api/v2/webhooks/:id/deliveriesLấ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ện order.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:
app.post('/webhook', async (req, res) => {
  // 1. Từ chối payload có chữ ký không hợp lệ
  if (!verifySignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = req.headers['x-sellfern-event'];

  // 2. Chỉ hành động trên order.status_changed; xác nhận im lặng mọi thứ khác
  if (event !== 'order.status_changed') {
    return res.status(200).json({ received: true, handled: false });
  }

  // 3. Xây embed Discord từ payload và đăng nó
  const embed = buildEmbed(req.body);
  await postToDiscord(embed);
  return res.status(200).json({ received: true, handled: true });
});
Bot ánh xạ mỗi trạng thái đơn hàng tới màu embed Discord (xám cho New, xanh dương cho In Production, xanh lá cho Shipped, đỏ cho Cancelled) và bao gồm mã theo dõi và đơn vị vận chuyển khi có. Ví dụ đi kèm một README bao gồm phát triển cục bộ với ngrok và triển khai lên Render hoặc Railway.

Xử lý sự cố

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ờ.
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).
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.
Đả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).