Webhooks

Để có được hiệu năng tốt nhất, Goship sử dụng webhook để đẩy thông tin theo phương thức bất đồng bộ thông qua việc listen các event trên Goship của bạn.

1. Danh sách các webhook events:

Bạn có thể sử dụng các webhook event dưới đây cho việc cập nhật và lưu trữ thông tin của mình:

  • Cập nhật trạng thái vận đơn
  • Nhận thông tin đối soát
  • Nhận báo lỗi

Các webhook đều sử dụng phương thức POST để push dữ liệu.

2. Cài đặt webhook

Truy cập vào trang quản lý đơn hàng, menu API mục Goship API Webhooks, bạn chọn Webhook event và điền 1 endpoint để listen event này. Sau đó chọn Add subscription.

Lưu ý:

  • Bạn nên sử dụng 1 secured url (https) để listen webhook event.
  • Bạn có thể sử dụng nhiều endpoint để listen 1 webhook event.

3. Xác thực webhook

Mỗi webhook request sẽ bao gồm 1 HTTP_X_GOSHIP_HMAC_SHA256 trong header. Nó được sinh ra từ việc mã hóa thông tin client_secret của bạn. Do vậy, hãy chú ý tới vấn đề bảo mật thông tin nếu bạn không muốn bị fake dữ liệu nhận được.

Để xác thực một webhook request từ Goship, bạn sẽ cần mã hóa các thông tin mà bạn có, sau đó so sánh với chuỗi giá trị của HTTP_X_GOSHIP_HMAC_SHA256. Nếu chúng khớp với nhau, bạn có thể sử dụng thông tin từ body request để cập nhật hoặc lưu trữ.

Code mẫu về việc mã hóa tạo ra chuỗi so sánh với HMAC của Goship (PHP):

<?php
        define('CLIENT_SECRET', 'bestshop_secret');

        function verify_webhook($data, $webhook_hmac){
                $compared_hmac = base64_encode(hash_hmac('sha256', json_encode($data), CLIENT_SECRET, true));
                return ($webhook_hmac == $compared_hmac);
        }

        $webhook_hmac = $_SERVER['HTTP_X_GOSHIP_HMAC_SHA256'];
        $data = json_decode(file_get_contents('php://input'), true);
        $verified = verify_webhook($data, $webhook_hmac);

        if ($verified) {
            // Update or insert
        }
?>

4. Nhận thông tin từ webhook

Sau khi bạn đã đăng ký thông tin nhận webhook thành công, Goship sẽ gửi các request mang thông tin tương ứng của webhook event theo phương thức POST tới cho bạn mỗi khi có event xảy ra.

Với mỗi event, dữ liệu request tới sẽ là khác nhau. Sau đây là các mẫu request theo webhook event:

1. Cập nhật trạng thái vận đơn

{
    "code": "GS123ABCDE",
    "weight": "400",
    "fee": "48000",
    "status": 900,
    "status_text": "Đơn mới",
    "message": "Goship đã nhận đơn hàng và đang tiến hành xử lý."
}

Trong đó:

  • code: Mã vận đơn của Goship
  • weight: Trọng lượng gói hàng mà Goship tiếp nhận
  • fee: Phí vận chuyển
  • status: Mã trạng thái vận đơn
  • status_text: Trạng thái vận đơn
  • message: Nội dung thông báo từ Goship

Khi bạn nhận được các thông tin này, bạn có thể cập nhật lại thông tin vận đơn cho chính xác.

Danh sách trạng thái vận đơn có thể xem tại Shipment status list

2. Nhận thông tin đối soát

{
    "code":  "PA3BR12O",
    "message": "Có đối soát đơn hàng mới ngày 20/02/2017"
}

Trong đó:

  • code là mã đối soát của Goship
  • message là nội dung thông báo từ Goship

Khi bạn nhận được các thông tin này, bạn có thể sử dụng code để lấy thông tin chi tiết của đối soát bao gồm tiền đối soát COD và vận đơn tương ứng. Bạn có thể tham khảo thêm chi tiết về việc lấy thông tin tại Đối soát

5. Phản hồi lại webhook

Bất cứ khi nào bạn nhận được webhook request từ Goship, hãy phản hồi lại với 1 HTTP status code là 200 OK. Bất kỳ HTTP status code không phải 200 đều bị Goship coi là chưa nhận được dữ liệu. Như thế, Goship sẽ thử gửi lại thông tin webhook cho bạn.

Sau 3 lần không thể gửi được, nó sẽ không thử gửi thêm nữa.