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.

• 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

{
  "is_ondemand_shipment": true,
  "gcode": "GS6ZE234V6",
  "code": "GAPBLXAE",
  "order_id": "SML-003749",
  "fee": 35650,
  "cod": 0,
  "status": 901,
  "message": "Chờ shipper qua lấy hàng",
  "description": "Chờ shipper qua lấy hàng",
  "tracking_url": "https://express.grab.com/track/exampleCode",
  "error": null,
  "error_txt": null,
  "cancel_at": null,
  "pickup_at": "2025-05-13T09:15:00+07:00",
  "delivery_at": null,
  "shipper_accept_at": "2025-05-13T08:45:00+07:00",
  "completed_at": null,
  "returned_at": null,
  "paths": [
    {
      "uuid": "GS123123",
      "status": "Chờ lấy hàng",
      "tracking_number": "GHN12345678",
      "tracking_url": "https://tracking.example.com/GHN12345678",
      "completed_at": null,
      "failed_at": null,
      "returned_at": null,
      "fail_note": null
    },
    {
      "uuid": "GS234234",
      "status": "Đang giao",
      "tracking_number": "GHN12345679",
      "tracking_url": "https://tracking.example.com/GHN12345679",
      "completed_at": null,
      "failed_at": null,
      "returned_at": null,
      "fail_note": null
    }
  ]
}

Trong đó:

• is_ondemand_shipment: Đánh dấu đây là đơn hoả tốc
• gcode: Mã đơn của Goship
• code: Mã đơn của hãng vận chuyển
• order_id: Mã vận đơn của bạn
• fee: Phí vận chuyển (đơn vị: VNĐ)
• cod: Giá tiền thu hộ từ người nhận (Cash on Delivery)
• status: Mã trạng thái vận đơn
• message: Trạng thái vận đơn (hiển thị dạng chữ, ví dụ: "Chờ shipper qua lấy hàng")
• description: Mô tả chi tiết trạng thái vận đơn (có thể giống hoặc khác message)
• tracking_url: Đường dẫn theo dõi vận đơn trên trang của hãng vận chuyển
• error: Mã lỗi nếu có lỗi xảy ra trong quá trình tạo đơn
• error_txt: Mô tả lỗi nếu có lỗi xảy ra trong quá trình tạo đơn
• cancel_at: Thời điểm đơn hàng bị huỷ (nếu có), định dạng ISO 8601
• pickup_at: Thời điểm shipper đến lấy hàng (nếu có)
• delivery_at: Thời điểm shipper bắt đầu giao hàng (nếu có)
• shipper_accept_at: Thời điểm shipper nhận đơn từ hệ thống
• completed_at: Thời điểm đơn giao thành công
• returned_at: Thời điểm đơn bị hoàn trả về (nếu có)
• paths: Danh sách các điểm giao/nhận trong hành trình của đơn hàng, mỗi phần tử gồm:
  • uuid: Mã định danh điểm giao/nhận
  • status: Trạng thái hiện tại tại điểm đó (dạng số)
  • message: Trạng thái hiện tại tại điểm đó (dạng chữ)
  • kind: Loại điểm giao/nhận
  • tracking_number: Mã vận đơn tại điểm đó (nếu có)
  • tracking_url: Đường dẫn theo dõi tại điểm đó
  • completed_at: Thời điểm hoàn thành tại điểm đó (nếu có)
  • failed_at: Thời điểm thất bại tại điểm đó (nếu có)
  • returned_at: Thời điểm bị hoàn trả tại điểm đó (nếu có)
  • fail_note: Ghi chú lý do thất bại (nếu có)

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.