DOCS
BerandaUntuk penyedia logistik Webhook

Dengarkan acara dengan webhook

Dapatkan notifikasi acara real-time untuk integrasi Zonos Anda.

Webhook menyediakan cara bagi Zonos untuk secara proaktif memberi tahu sistem eksternal Anda setiap kali acara tertentu terjadi. Ketika acara yang dilanggan terjadi, Zonos akan mengirim permintaan HTTP POST ke URL webhook yang Anda tentukan. Badan permintaan akan berisi detail acara, memungkinkan sistem Anda menangani acara secara terprogram.

Webhook berguna untuk mengintegrasikan Zonos dengan platform lain, memicu alur kerja otomatis, dan menjaga data tetap sinkron di seluruh sistem secara real-time. Misalnya, Anda dapat menggunakan webhook untuk:

  • Perbarui sistem manajemen pesanan Anda ketika pesanan dibuat di Zonos
  • Beri tahu penyedia pemenuhan Anda ketika pengiriman dibatalkan
  • Catat perubahan status pesanan internasional untuk tujuan audit

Jenis webhook 

Semua jenis webhook yang tersedia disertakan dalam enum WebhookType. Contoh payload untuk masing-masing dapat ditemukan dalam panduan Jenis acara kami.

Membuat webhook 

Untuk membuat webhook melalui 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}

Penting: Simpan nilai secret saat Anda membuat webhook — nilai ini hanya dikembalikan di sini, dan Anda akan memerlukannya untuk memverifikasi tanda tangan webhook. Lihat Memverifikasi tanda tangan webhook di bawah.

Edit detail webhook 

Untuk mengedit webhook yang ada melalui API:

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

Memverifikasi tanda tangan webhook 

Setiap permintaan webhook yang dikirim Zonos menyertakan header zonos-signature sehingga Anda dapat memastikan permintaan tersebut benar-benar berasal dari Zonos dan payload-nya tidak diubah selama pengiriman.

Nilai header memiliki format:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — waktu, dalam milidetik epoch Unix, saat permintaan ditandatangani.
  • hmac — tanda tangan HMAC-SHA256 dari isi permintaan JSON mentah, dihitung menggunakan secret webhook Anda sebagai kunci dan dienkode Base64.

Untuk memverifikasi permintaan:

  1. Uraikan nilai timestamp dan hmac dari header zonos-signature.
  2. Hitung tanda tangan HMAC-SHA256 Anda sendiri atas isi permintaan mentah yang belum diurai, menggunakan secret yang Anda terima saat membuat webhook.
  3. Bandingkan tanda tangan yang Anda hitung dengan nilai hmac menggunakan perbandingan waktu konstan, dan tolak permintaan jika keduanya tidak cocok.
  4. Secara opsional, tolak permintaan yang timestamp-nya lebih tua dari beberapa menit untuk mencegah replay dari permintaan yang direkam. Zonos sendiri tidak menerapkan batas waktu pengiriman, jadi pemeriksaan ini terserah Anda.
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}

Catatan: Jika Anda mengonfigurasi header kustom pada webhook Anda, header tersebut juga disertakan apa adanya pada setiap permintaan bersama zonos-signature.

Lihat log webhook 

Untuk melihat log webhook melalui 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

Apakah halaman ini bermanfaat?

Dapatkan dukungan·Dokumen hukum·© 2026 Zonos
Di halaman ini:
  • Dengarkan acara dengan webhook
  • Jenis webhook
  • Membuat webhook
  • Edit detail webhook
  • Memverifikasi tanda tangan webhook
  • Lihat log webhook