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
    }
  });

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.

Xem thêm

Xem chi tiết cấu trúc payload của event và API quản lý webhook (thêm/xóa endpoint) tại Webhook Reference.