Webhook Reference

Trang này mô tả cấu trúc payload của các webhook event và API để quản lý (thêm/xóa) endpoint nhận webhook. Xem hướng dẫn cài đặt và xác thực webhook tại Webhooks.

Payload sự kiện

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,
  "carrier_short_name": "ghn",
  "amount_return_shop": -35650,
  "update_time": 1735700400
}

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ó
• carrier_short_name: Tên hãng vận chuyển
• amount_return_shop: Số tiền trả lại cho shop (Đã bao gồm cả COD và các chi phí của vận đơn, trường hợp đơn hàng không có COD, số tiền < 0, đối tác sẽ cần thanh toán các chi phí vận đơn)
• update_time: Thời gian cập nhật của trạng thái mới nhất (UNIX timestamp GMT +7)

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

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"
}