Goship Webhooks

Thay vì phải lấy dữ liệu một cách thủ công và bị động, bạn có thể sử dụng Goship Webhooks để nhận các update mới nhất một cách tự động.

Goship API cung cấp webhook dựa trên các event xảy ra trên hệ thống Goship API.

Webhook events:

Listen các webhook events dưới đây để cập nhật thông tin mới nhất cho hệ thống của bạn.

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

Cài đặt webhook

Mỗi khi có cập nhật mới, hệ thống Goship API sẽ đẩy thông tin đó tới một url endpoint của bạn. Bạn cần đăng ký url endpoint theo các webhook event tương ứng.

Trên giao diện Kết nối API mục Goship API Webhooks, bạn chọn Webhook event và nhập vào endpoint để listen event này. Bấm Add subscription.

Goship Webhook

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

Xác thực webhook

Để tránh việc bị tấn công "Man in the middle", mỗi webhook request từ Goship API sẽ bao gồm 1 X-Goship-Hmac-SHA256 trong header.

Giá trị của checksum được sinh ra từ việc mã hóa thông tin credentials của bạn và dữ liệu Goship gửi tới. Sau đó so sánh với chuỗi giá trị checksum của 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ữ.

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

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

  $webhook_hmac = $_SERVER['X-Goship-Hmac-SHA256'];
  $data = json_decode(file_get_contents('php://input'), true);
  $verified = verify_webhook($data, $webhook_hmac);

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

const express = require('express');
const router = express.Router();
const { Base64 } = require('js-base64');
const crypto = require('crypto');
const client_secret = env.process.client_secret
const hmac = crypto.createHmac('sha256', client_secret);

function verify_webhook(data, webhook_hmac) {
  const hashed = hmac.update(JSON.stringify(data));
  const compared_hmac = Base64.fromUint8Array(hashed.digest('hex'));
  return webhook_hmac == compared_hmac;
}

// webhook listen route
router.post('/listen', function (req, res) {
  const webhook_hmac = req.headers['X-Goship-Hmac-SHA256'];
  const data = JSON.parse(req.body);
  const verified = verify_webhook(data, webhook_hmac);

  if (verified) {
    // Update or insert
  }
});

Nhận thông tin từ webhook

Sau khi bạn đã đăng ký thông tin webhook thành công, Goship sẽ gửi các request mang thông tin update của webhook event tới url endpoint mà bạn đã đăng ký.

Các webhook event sẽ có format request body khác nhau:

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

{
  "gcode": "GS6ZE234V6",
  "code": "GAPBLXAE",
  "order_id": "SML-003749",
  "weight": "2360.0000000000005",
  "fee": "35650",
  "cod": "0",
  "payer": "0",
  "status": "901",
  "message": "Chờ shipper qua lấy hàng",
  "tracking_url": "https://donhang.ghn.vn/?order_code=GAPBLXAE",
}

Trong đó:

code: Mã đơ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.

Xem thêm danh sách trạng thái vận đơn

Phản hồi lại webhook

Mỗi khi nhận được webhook request từ Goship API, bạn cần phản hồi lại với 1 HTTP status code là 200 OK.

Một request nếu không có phản hồi với status code là 200, Goship sẽ request lại sau 3 phút.

Sau 3 lần request thất bại, tác vụ sẽ bị hủy để tránh request quá nhiều tới hệ thống của bạn.