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

{
  "gcode": "GS6ZE234V6",
  "code": "GAPBLXAE",
  "order_id": "SML-003749",
  "weight": "2360.0000000000005",
  "fee": "35650",
  "cod": "0",
  "payer": "0",
  "status": "901",
  "status_text": "Chờ lấy hàng",
  "message": "Chờ shipper qua lấy hàng",
  "tracking_url": "https://donhang.ghn.vn/?order_code=GAPBLXAE",
  "description": "Shipper đang trên đường đến lấy hàng",
  "sorting_code": "GAPBLXAE",
  "return_sorting_code": "HN-01-01-TM01",
  "is_return": 0,
  "is_part_delivery": 0,
  "is_lost"  : 0,
}

Trong đó:

• gcode: Mã đơn của Goship
• code: Mã đơn của hãng vận chuyển
• order_id: Mã đơn của đối tác mà
• weight: Trọng lượng gói hàng mà Goship tiếp nhận
• fee: Phí vận chuyển
• cod: Tiền thu hộ
• payer: Người trả phí vận chuyển. Giá trị của trường này có thể là:
  • 0: Khách trả
  • 1: Shop trả
• 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
• tracking_url: Link theo dõi vận đơn của hãng vận chuyển
• description: Mô tả trạng thái vận đơn
• sorting_code: Mã phân loại vận đơn
• return_sorting_code: Mã phân loại vận đơn trả hàng
• is_return: Trả hàng hay không. Giá trị của trường này có thể là:
  • 0: Không
  • 1: Có
• is_part_delivery: Giao hàng một phần hay không. Giá trị của trường này có thể là:
  • 0: Không
  • 1: Có
• is_lost: Mất hàng hay không. Giá trị của trường này có thể là:
  • 0: Không
  • 1: 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.

Webhook API

Lấy danh sách webhook

GET https://sandbox.goship.io/api/v2/webhooks

Response data

{
  "code": 200,
  "status": "success",
  "data": [
    {
      "id": 12,
      "event": "Tất cả",
      "endpoint": "https://example.com/webhooks/goship",
      "created_at": "2026-03-19 09:30:00",
      "updated_at": "2026-03-19 09:30:00"
    }
  ]
}

Trong đó:

• id: id webhook, dùng để gọi API xóa webhook
• event: tên sự kiện; với flow Open API v2 hiện tại luôn là Tất cả
• endpoint: URL nhận callback webhook
• created_at: thời điểm tạo webhook
• updated_at: thời điểm cập nhật webhook gần nhất

Tạo webhook

POST https://sandbox.goship.io/api/v2/webhooks

Body:

{
  "endpoint": "https://example.com/webhooks/goship"
}

Trong đó:

• endpoint: URL mà hệ thống sẽ gọi đến khi bắn webhook

Response data:

{
  "code": 200,
  "status": "success",
  "data": {
    "id": 12,
    "event": "Tất cả",
    "endpoint": "https://example.com/webhooks/goship",
    "created_at": "2026-03-19 09:30:00",
    "updated_at": "2026-03-19 09:30:00"
  }
}

Trong đó:

• id: id webhook
• event: tên sự kiện mặc định, luôn là Tất cả
• endpoint: URL nhận webhook
• created_at: thời điểm tạo webhook
• updated_at: thời điểm cập nhật webhook gần nhất

Xóa webhook

DELETE https://sandbox.goship.io/api/v2/webhooks/{id}

Trong đó:

• id: id webhook cần xóa, lấy từ API danh sách webhook

Response data:

{
  "code": 200,
  "status": "success",
  "data": [],
  "message": "Resource Deleted"
}

Trong đó:

• code: mã trạng thái của API
• status: trạng thái xử lý
• data: dữ liệu trả về, ở đây là rỗng sau khi xóa thành công
• message: thông báo kết quả xóa

Response khi không tìm thấy webhook

{
  "code": 404,
  "status": "error",
  "data": [],
  "message": "Resource Not Found"
}