DOCS
Ana sayfaLojistik sağlayıcıları için Web Kancaları

Web kancaları ile olayları dinleyin

Zonos entegrasyonunuz için gerçek zamanlı olay bildirimleri alın.

Web kancaları, Zonos'un belirli olaylar meydana geldiğinde dış sistemlerinizi proaktif olarak bilgilendirmesinin bir yoludur. Abone olunan olay meydana geldiğinde, Zonos belirttiğiniz web kancası URL'sine HTTP POST isteği gönderecektir. İstek gövdesi olay ayrıntılarını içerecek ve sisteminizin olayı programlı olarak işlemesine izin verecektir.

Web kancaları Zonos'u diğer platformlarla entegre etmek, otomatik iş akışlarını tetiklemek ve verileri sistemler arasında gerçek zamanlı olarak senkronize tutmak için yararlıdır. Örneğin, web kancalarını aşağıdaki amaçlarla kullanabilirsiniz:

  • Zonos'ta bir sipariş oluşturulduğunda sipariş yönetim sisteminizi güncelleyin
  • Gönderim iptal edildiğinde yerine getirme sağlayıcınızı bilgilendirin
  • Uluslararası siparişlerin durum değişikliklerini denetim amaçlı kaydedin

Web kancası türleri 

Tüm kullanılabilir web kancası türleri WebhookType numaralandırmasında yer almaktadır. Her biri için örnek yükler Olay Türleri kılavuzunda bulunabilir.

Web kancaları oluşturma 

API aracılığıyla web kancası oluşturmak için:

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}

Önemli: Web kancasını oluşturduğunuzda secret değerini kaydedin — bu değer yalnızca burada döndürülür ve web kancası imzalarını doğrulamak için gerekli olacaktır. Aşağıdaki Web kancası imzalarını doğrulama bölümüne bakın.

Web kancası ayrıntılarını düzenleyin 

API aracılığıyla mevcut bir web kancasını düzenlemek için:

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

Web kancası imzalarını doğrulama 

Zonos'un gönderdiği her web kancası isteği, isteğin gerçekten Zonos'tan geldiğini ve yükün (payload) iletim sırasında değiştirilmediğini doğrulamanızı sağlayan bir zonos-signature başlığı içerir.

Başlık değeri şu biçimdedir:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — isteğin imzalandığı zaman, Unix epoch milisaniye cinsinden.
  • hmac — ham JSON istek gövdesinin, web kancanızın gizli anahtarı anahtar olarak kullanılarak hesaplanan ve Base64 ile kodlanan HMAC-SHA256 imzası.

Bir isteği doğrulamak için:

  1. zonos-signature başlığından timestamp ve hmac değerlerini ayrıştırın.
  2. Web kancasını oluştururken aldığınız gizli anahtarı kullanarak, ham ve ayrıştırılmamış istek gövdesi üzerinden kendi HMAC-SHA256 imzanızı hesaplayın.
  3. Hesapladığınız imzayı sabit zamanlı bir karşılaştırma kullanarak hmac değeriyle karşılaştırın ve eşleşmezlerse isteği reddedin.
  4. Yakalanan bir isteğin tekrar oynatılmasına (replay) karşı korunmak için isteğe bağlı olarak timestamp değeri birkaç dakikadan daha eski olan istekleri reddedebilirsiniz. Zonos, teslimat için herhangi bir zaman penceresi zorunlu kılmaz; bu nedenle bu kontrol size bağlıdır.
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}

Not: Web kancanızda özel başlıklar yapılandırdıysanız, bunlar da her istekte zonos-signature ile birlikte olduğu gibi (aynen) dahil edilir.

Web kancası günlüklerini görüntüleyin 

API aracılığıyla web kancası günlüklerini görüntülemek için:

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

Bu sayfa faydalı mıydı?

Destek alın·Hukuki belgeler·© 2026 Zonos
Bu sayfada:
  • Web kancaları ile olayları dinleyin
  • Web kancası türleri
  • Web kancaları oluşturma
  • Web kancası ayrıntılarını düzenleyin
  • Web kancası imzalarını doğrulama
  • Web kancası günlüklerini görüntüleyin