Webhook

Webhook là HTTP callbacks, chúng thường được kích hoạt bởi một số sự kiện thay đổi dữ liệu được xác định trước.

Webhook là gì?

Webhook là HTTP callbacks, chúng thường được kích hoạt bởi một số sự kiện nhất định. Khi một trong những sự kiện đó được kích hoạt làm thay đổi dữ liệu, thì hệ thống của Shippo sẽ gửi HTTP request tới URL đã được cấu hình webhook.

Ví dụ minh họa: Enpoint: POST https://doitac.example.com/updateDeliveryOrder

Để cấu hình webhook, Shop vui lòng liên hệ trực tiếp với đội phát triển Shippo. Chúng tôi sẽ sớm bổ sung chức năng cho phép Shop chủ động cấu hình thông tin này.

Verify URL Webhook

Để gửi request call một API, Request Header của bạn phải có các thông tin sau:

Cách 1: Verify sử dụng token:

  • Accept: application/json

  • Content-Type: application/json

  • Authorization: Bearer {access token}

Cách 2: Verify sử dụng username/password:

  • Accept: application/json

  • Content-Type: application/json

  • Username: username

  • Password: password

Thay đổi vận đơn

Giả sử đối tác cung cấp một URL https://doitac.example.com/updateDeliveryOrder đã được cấu hình webhook.

Khi một sự kiện làm thay đổi thông tin, trạng thái của vận đơn liên quan đến đối tác (hoặc Shop trong trường hợp Shop tích hợp API với Shippo), hệ thống Shippo sẽ gửi một POST Request đến URL đã cấu hình webhook mà đối tác cung cấp. Request của Shippo gửi bao gồm các thông tin chi tiết về vận đơn sau khi thay đổi.

Shippo sử dụng HTTP Status code = 200 để xác định có gửi được cập nhật sang đối tác có thành công hay không.

Cấu trúc dữ liệu hook trả về khi có thay đổi/tạo mới vận đơn

{
triggers: [] // các trigger events
time: //Thời gian,
delivery_order: // dữ liệu vận đơn sau khi thay đổi, xem tại Dữ liệu > Vận đơn
}

Danh sách các triggers

Triggers

Mô tả

DELIVERY_ORDER_FEE_CREATE

Tạo Vận đơn

DELIVERY_ORDER_UPDATE_SENDER_INFO

Update thông tin người gửi (pickupContact, pickupPhone, pickupLocationId, pickupDetailAddress, pickupNote)

DELIVERY_ORDER_UPDATE_RECEIVER_INFO

Update thông tin người nhận (receiverName, receiverPhone, deliverLocationId, deliverDetailAddress, deliveryNote)

DELIVERY_ORDER_UPDATE_FINANCE

Update thông tin tài chính của Vận đơn (cod, realCod, totalMerchantFee, totalFee)

DELIVERY_ORDER_UPDATE_STATE

Update trạng thái Vận đơn (state)

DELIVERY_ORDER_UPDATE_FEATURES

Update các features của Vận đơn(features: INSURANCE, EVENING, STC, SCN)

DELIVERY_ORDER_FEE_UPDATE_FEE

Update phí của Vận đơn (quantity, amount, chargeType)

DELIVERY_ORDER_CREATE

Tạo vận đơn

DELIVERY_ORDER_UPDATE_GOODS

Update danh mục hàng hóa (goods)

DELIVERY_ORDER_UPDATE_TRANSIT_FAILURE_NOTES

Update khi đơn lấy hoặc giao thất bại (transitFailureNotes)

post
Đăng ký Webhook

https://apix.shippo.vn/integration/integration_merchant_trigger
Request
Response
Request
Headers
Authorization
required
string
Bearer {accesstoken}
Content-Type
required
string
application/json
Body Parameters
clientKey
required
string
Là client của Application đăng ký
payloadUrl
required
string
Là URL nhận Webhook Shippo gửi sang mỗi khi có thay đổi
token
optional
string
Là token cần xác thực khi Shippo call payloadUrl gửi dữ liệu.
Response
200: OK
{
"clientId": 1356,
"userId": 1001313,
"triggerId": "1,2,3,4,6,7,12,13,17,19",
"state": "ACTIVE",
"payloadUrl": "https://localhost.requestcatcher.com",
"httpMethod": "POST",
"verifyMethod": {
"type": "token",
"token": ""
},
"createdAt": "2020-01-30T07:49:24.763Z",
"updatedAt": "2020-01-30T07:49:24.763Z"
}
400: Bad Request
{
"error": {
"httpCode": 400,
"name": "GET_TOKEN_FAIL",
"message": "" // thông báo lỗi
}

Ví dụ: Request Body

{
"clientKey": "MTMzNzo4MTAxMzY2ZTdjM2IwMTE3YjEzNTEzYWMwNjMzMTdkNTdkMjNkY2U0",
"payloadUrl":"https://localhost:3000",
"token":"1IT8azDvkjBz-CfEbMTBlUn5LtMbh5w9QrmJPGyqzm80"
}

Cấu trúc dữ liệu trả về

Trường

Dữ liệu

clientId

integer

ID của Application

userId

integer

ID của tài khoản Shop đăng ký Webhook

triggerId

string

Chuỗi id các triggers trên hệ thống Shippo

state

string

Trạng thái Webhook

payloadUrl

string

Link nhận Webhoook

httpMethod

string

Method khi call API gửi webhook

verifyMethod

object

Phương thức verify

createdAt

timestamptz

Thời gian đăng ký

Hiện tại Shippo chưa hỗ trợ API thay đổi webhook. Nếu người dùng cần thay đổi, vui lòng liên hệ Shippo hỗ trợ.