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 Zogo Webhooks để nhận các update mới nhất một cách tự động.

Zogo API cung cấp webhook dựa trên các event xảy ra trên hệ thống Zogo 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 Zogo 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 Zogo 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ừ Zogo API sẽ bao gồm 1 x-zogo-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 Zogo gửi tới. Sau đó so sánh với chuỗi giá trị checksum của x-zogo-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-zogo-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-zogo-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, Zogo 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 Zogo
• weight: Trọng lượng gói hàng mà Zogo 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ừ Zogo

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ừ Zogo 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, Zogo 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.