Tham chiếu Webhook

Tóm tắt

Đăng ký một endpoint HTTPS để Elim chủ động gọi vào hệ thống của bạn mỗi khi đơn hàng hoặc thanh toán đổi trạng thái — thay cho việc hỏi trạng thái liên tục. Trang này mô tả sự kiện, endpoint quản lý, cấu trúc payload, cách xác minh chữ ký và chính sách thử lại.

Để xem webhook nằm ở đâu trong vòng đời đơn hàng, xem Hướng dẫn đặt & thanh toán đơn Taobao/1688 và Tham chiếu API đơn hàng.

Mọi endpoint yêu cầu xác thực JWT (Authorization: Bearer <token>) hoặc API Key (x-api-key).

Sự kiện

Đăng ký sự kiện nào thì chỉ nhận sự kiện đó. Thường đăng ký cả hai.

Endpoint quản lý đăng ký

Prefix /v1/webhooks.

Body tạo đăng ký

{
  "url": "https://he-thong-cua-ban.example/webhooks/elim",
  "events": ["order.updated", "payment.updated"],
  "is_active": true
}

secret chỉ trả về ngay sau khi tạo hoặc rotate-secret. Lưu vào nơi an toàn — bạn cần nó để xác minh mọi request. Mất secret thì gọi rotate-secret để cấp lại (chữ ký cũ ngừng hợp lệ).

Cấu trúc payload

Cả hai sự kiện dùng chung một dạng — khác nhau ở trường event:

{
  "id": "evt_4a1f2c...",
  "event": "payment.updated",
  "created_at": "2026-06-19T00:00:00.000Z",
  "data": {
    "order": {
      "id": "ORD0000000123",
      "platform": "taobao",
      "order_id": "123456789",
      "status": "paid",
      "payment_status": "paid",
      "platform_payment_status": "success",
      "total_amount_cny": 123.45,
      "updated_at": "2026-06-19T00:00:00.000Z"
    }
  }
}

Xử lý phía bạn: tra data.order.id, cập nhật trạng thái đơn trong hệ thống, rồi trả HTTP 2xx. Payload có thể đến không đúng thứ tự — luôn tin updated_at mới hơn và bỏ qua sự kiện cũ hơn trạng thái bạn đang giữ.

Header mỗi lần gọi

Xác minh chữ ký

Chuỗi ký: "{X-Elim-Timestamp}.{raw_json_body}" — dùng body thô nguyên trạng, không parse rồi serialize lại.

Thuật toán: HMAC-SHA256(secret, chuỗi_ký), so sánh với phần sau sha256= trong X-Elim-Signature bằng hàm so sánh an toàn thời gian.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyElimWebhook(
  secret: string,
  timestamp: string,
  rawBody: string,
  signature: string,
): boolean {
  const expected = `sha256=${createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')}`;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Từ chối request có X-Elim-Timestamp lệch quá xa hiện tại (ví dụ hơn 5 phút) để hạn chế bị phát lại.

Chính sách thử lại

Xem kết quả từng lần gửi ở GET /v1/webhooks/:id/deliveries. Dùng POST /v1/webhooks/:id/test để kiểm tra nhanh cấu hình nhận.

Bảo mật

• URL ở môi trường thật phải là HTTPS. Môi trường dev chấp nhận localhost.
• IP nội bộ / private / metadata bị chặn ở môi trường thật.
• secret chỉ hiển thị sau khi tạo hoặc rotate-secret.
• Payload không chứa mật khẩu, API key, JWT hay access token nền tảng.

Nếu chưa dựng webhook

Hỏi trạng thái trực tiếp bất cứ lúc nào bằng GET /v1/orders/:id — mỗi lần gọi, Elim tự đồng bộ trạng thái mới nhất từ nền tảng trước khi trả về. Xem Tham chiếu API đơn hàng.

Liên kết liên quan

• Tham chiếu API đơn hàng
• Hướng dẫn đặt & thanh toán đơn Taobao/1688
• Hướng dẫn xác thực