Chuyển tới nội dung chính

Tổng quan về Webhooks

Webhooks cho phép nhận thông báo HTTP theo thời gian thực cho các sự kiện và hành động trên TikTok Shop, được truyền an toàn qua HTTPS đến HTTP server đã đăng ký.

Image

  1. App đăng ký topic Order Status Update cho một shop và lắng nghe các sự kiện cập nhật trạng thái đơn hàng
  2. App chỉ định một HTTPS endpoint được lưu trữ trên app server để nhận các sự kiện của topic.
  3. Một đơn hàng trong shop được tạo hoặc trạng thái đã thay đổi.
  4. Sự kiện được phát hành tới topic Order Status Update.
  5. TikTok Shop gửi webhook kèm payload tải lên trạng thái đơn hàng đến endpoint đăng ký đã được khai báo.

Các trường hợp sử dụng​

Các trường hợp sử dụng webhook phổ biến bao gồm:

  • Nhận thông báo khi trạng thái đơn hàng được cập nhật
  • Nhận thông báo khi địa chỉ người nhận của đơn hàng được cập nhật
  • Nhận thông báo khi trạng thái trả hàng được cập nhật
  • Nhận thông báo khi trạng thái sản phẩm được cập nhật

Lưu ý​

Do có thể xảy ra các sự cố mạng và những yếu tố bất định khác, bạn không thể hoàn toàn phụ thuộc vào webhooks. Bạn cần có logic nghiệp vụ riêng, chẳng hạn như kéo đơn hàng thông qua các tác vụ định kỳ (scheduled tasks), v.v.

Header và Body của Webhooks​

TikTok Shop Partners Center đẩy thông báo đến nhà phát triển và đặt chữ ký (signature) vào trường "Authorization" của HTTP request header.

Chữ ký được tạo bằng HMAC-SHA256 và cần được nhà phát triển xác minh.

Chữ ký được tạo như sau:

  1. Giả sử app key của bạn là abcdef.
  2. Giả sử webhook payload là:

PLAINTEXTWord Wrap

{"type":1,"tts_notification_id":"7380066284010030890","shop_id":"7495540735365777507","timestamp":1718305585,"data":{"is_on_hold_order":true,"order_id":"576653688135258178","order_status":"UNPAID","update_time":1718305585}}
  1. Nối {app key}{webhook payload} thành chuỗi cơ sở của chữ ký (signature base string) mà không định dạng gì khi dán các chuỗi:

PLAINTEXTWord Wrap

abcdef{"type":1,"tts_notification_id":"7380066284010030890","shop_id":"7495540735365777507","timestamp":1718305585,"data":{"is_on_hold_order":true,"order_id":"576653688135258178","order_status":"UNPAID","update_time":1718305585}}
  1. Giả sử app secret của bạn là 123 dùng làm khóa ký (signing key).
  2. Tính chữ ký bằng cách truyền chuỗi cơ sở của chữ ký và khóa ký vào thuật toán băm hmac-sha256. Chữ ký thu được là:

PLAINTEXTWord Wrap

5dec0f11ec2f6783b8deee53c9ffbf8d024302f7c7e7fa55a35d17629031ac05

Body​

Tất cả thông báo webhook từ TikTok Shop sẽ bao gồm các tham số payload sau

Param NameSampleDescription
type1Định danh của từng loại thông báo
shop_id123455Định danh của TikTok Shop
timestamp1627587506Thời điểm (timestamp) khi thông báo được đẩy đi
data"data": {
"order_id": "1X2X3X4X5",
"order_status": "CANCEL",
"update_time": 1627587505}Đối tượng chứa các tham số nghiệp vụ liên quan đến loại thông báo cụ thể.

Mẫu​

Mẫu yêu cầu curl:

JSONWord Wrap

curl   --location --request POST 'https://www.bing.com/webhook' \  
--header 'Content-Type: application/json' \  
--header 'Authorization: 46c0d0a3299661dc92888f7da8ba2321f240e460e2b005389353432a1062b777'\  
--data-raw '{  
    "type": 1,  
    "shop_id": "7494049642642441621",  
    "timestamp": 1644412885,  
    "data": {  
        "order_id": "576486316948490001",  
        "order_status": "UNPAID",  
        "update_time": 1644412885  
    }  
}'

➡️ Xem danh sách các webhooks của chúng tôi tại đây