DOCS
Trang chủCho các nhà cung cấp logistics Webhooks

Lắng nghe các sự kiện bằng webhooks

Nhận thông báo sự kiện thời gian thực cho tích hợp Zonos của bạn.

Webhooks cung cấp một cách để Zonos chủ động thông báo cho các hệ thống bên ngoài của bạn bất cứ khi nào các sự kiện nhất định xảy ra. Khi sự kiện được đăng ký xảy ra, Zonos sẽ gửi một yêu cầu HTTP POST đến URL webhook bạn chỉ định. Phần thân của yêu cầu sẽ chứa chi tiết sự kiện, cho phép hệ thống của bạn xử lý sự kiện theo chương trình.

Webhooks rất hữu ích cho việc tích hợp Zonos với các nền tảng khác, kích hoạt các quy trình công việc tự động và giữ dữ liệu được đồng bộ hóa trên các hệ thống theo thời gian thực. Ví dụ: bạn có thể sử dụng webhooks để:

  • Cập nhật hệ thống quản lý đơn hàng của bạn khi tạo đơn hàng trong Zonos
  • Thông báo cho nhà cung cấp dịch vụ hoàn tất đơn hàng của bạn khi lô hàng bị hủy
  • Ghi lại các thay đổi trạng thái của các đơn hàng quốc tế cho mục đích kiểm toán

Các loại webhook 

Tất cả các loại webhook có sẵn được bao gồm trong enum WebhookType. Các ví dụ về payload cho mỗi loại có thể được tìm thấy trong hướng dẫn Các Loại Sự Kiện của chúng tôi.

Tạo webhooks 

Để tạo webhook qua API:

1mutation WebhookCreate($input: WebhookCreateInput!) {
2 webhookCreate(input: $input) {
3 id
4 url
5 type
6 status
7 secret
8 headers {
9 key
10 }
11 }
12}

Quan trọng: Lưu lại giá trị secret khi bạn tạo webhook — giá trị này chỉ được trả về ở đây, và bạn sẽ cần nó để xác minh chữ ký webhook. Xem Xác minh chữ ký webhook bên dưới.

Chỉnh sửa chi tiết webhook 

Để chỉnh sửa webhook hiện có qua API:

1mutation WebhookUpdate($input: WebhookUpdateInput!) {
2 webhookUpdate(input: $input) {
3 id
4 url
5 type
6 status
7 }
8}

Xác minh chữ ký webhook 

Mỗi yêu cầu webhook mà Zonos gửi đều bao gồm một header zonos-signature để bạn có thể xác nhận rằng yêu cầu thực sự đến từ Zonos và payload không bị thay đổi trong quá trình truyền tải.

Giá trị header có định dạng:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — thời điểm yêu cầu được ký, tính bằng mili giây theo Unix epoch.
  • hmac — chữ ký HMAC-SHA256 của phần thân yêu cầu JSON gốc, được tính bằng secret của webhook làm khóa và mã hóa Base64.

Để xác minh một yêu cầu:

  1. Phân tích các giá trị timestamp và hmac từ header zonos-signature.
  2. Tính chữ ký HMAC-SHA256 của riêng bạn trên phần thân yêu cầu thô, chưa được phân tích, sử dụng secret bạn nhận được khi tạo webhook.
  3. So sánh chữ ký bạn tính được với giá trị hmac bằng cách so sánh thời gian không đổi (constant-time comparison), và từ chối yêu cầu nếu chúng không khớp.
  4. Tùy chọn, từ chối các yêu cầu có timestamp cũ hơn vài phút để phòng chống việc phát lại (replay) của một yêu cầu đã bị chặn. Zonos không tự áp đặt giới hạn thời gian gửi, vì vậy việc kiểm tra này là tùy thuộc vào bạn.
1const crypto = require('crypto');
2 
3function verifyZonosWebhook(rawBody, signatureHeader, secret) {
4 const [timestampPart, hmacPart] = signatureHeader.split(',');
5 const receivedHmac = hmacPart.split('=')[1];
6 
7 const expectedHmac = crypto
8 .createHmac('sha256', secret)
9 .update(rawBody)
10 .digest('base64');
11 
12 const receivedBuffer = Buffer.from(receivedHmac);
13 const expectedBuffer = Buffer.from(expectedHmac);
14 
15 if (receivedBuffer.length !== expectedBuffer.length) {
16 return false;
17 }
18 
19 return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
20}

Lưu ý: Nếu bạn đã cấu hình các header tùy chỉnh cho webhook của mình, chúng cũng sẽ được bao gồm nguyên văn trong mọi yêu cầu cùng với zonos-signature.

Xem nhật ký webhook 

Để xem nhật ký webhook qua API:

1query WebhookLogs(
2$first: Int
3$after: String
4$filter: WebhookLogsFilterInput
5) {
6 webhookLogs(first: $first, after: $after, filter: $filter) {
7 edges {
8 node {
9 id
10 type
11 url
12 createdAt
13 responseStatus
14 }
15 }
16 }
17}
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

WebhookCreateInput WebhookLogsFilterInput WebhookUpdateInput

MUTATIONS

webhookCreate webhookUpdate

Trang này có hữu ích không?

Nhận hỗ trợ·Tài liệu pháp lý·© 2026 Zonos
Trên trang này:
  • Lắng nghe các sự kiện bằng webhooks
  • Các loại webhook
  • Tạo webhooks
  • Chỉnh sửa chi tiết webhook
  • Xác minh chữ ký webhook
  • Xem nhật ký webhook