DOCS
Strona głównaDla dostawców logistyki Webhooki

Słuchaj zdarzeń za pośrednictwem webhooków

Otrzymuj powiadomienia o zdarzeniach w czasie rzeczywistym dla twojej integracji Zonos.

Webhooki umożliwiają Zonosowi proaktywnie powiadamiać twoje systemy zewnętrzne, gdy następują określone zdarzenia. Gdy wystąpi zarejestrowane zdarzenie, Zonos wyśle żądanie HTTP POST na adres URL webhooka, który określisz. Treść żądania będzie zawierać szczegóły zdarzenia, umożliwiając twoim systemom obsługę zdarzenia programowo.

Webhooki są przydatne do integracji Zonosa z innymi platformami, wyzwalania zautomatyzowanych przepływów pracy i utrzymywania synchronizacji danych w systemach w czasie rzeczywistym. Na przykład możesz użyć webhooków do:

  • Aktualizacji systemu zarządzania zamówieniami, gdy zamówienie zostanie utworzone w Zonosie
  • Powiadomienia dostawcy realizacji, gdy wysyłka zostanie anulowana
  • Logowania zmian statusu zamówień międzynarodowych w celach audytu

Typy webhooków 

Wszystkie dostępne typy webhooków są zawarte w wyliczeniu WebhookType. Przykładowe ładunki dla każdego można znaleźć w naszym przewodniku Typy zdarzeń.

Tworzenie webhooków 

Aby utworzyć webhook za pośrednictwem 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}

Ważne: Zapisz wartość secret podczas tworzenia webhooka — jest ona zwracana tylko tutaj i będzie ci potrzebna do weryfikacji podpisów webhooków. Zobacz Weryfikacja podpisów webhooków poniżej.

Edytuj szczegóły webhooka 

Aby edytować istniejący webhook za pośrednictwem API:

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

Weryfikacja podpisów webhooków 

Każde żądanie webhooka wysyłane przez Zonos zawiera nagłówek zonos-signature, dzięki któremu możesz potwierdzić, że żądanie rzeczywiście pochodzi od Zonos i że jego treść nie została zmieniona podczas przesyłania.

Wartość nagłówka ma format:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — czas, w milisekundach epoki Uniksa, w którym żądanie zostało podpisane.
  • hmac — podpis HMAC-SHA256 surowej treści żądania JSON, obliczony przy użyciu sekretu twojego webhooka jako klucza i zakodowany w formacie Base64.

Aby zweryfikować żądanie:

  1. Wyodrębnij wartości timestamp i hmac z nagłówka zonos-signature.
  2. Oblicz własny podpis HMAC-SHA256 na podstawie surowej, nieprzetworzonej treści żądania, używając sekretu otrzymanego podczas tworzenia webhooka.
  3. Porównaj obliczony podpis z wartością hmac, stosując porównanie w czasie stałym, i odrzuć żądanie, jeśli się nie zgadzają.
  4. Opcjonalnie odrzucaj żądania, w których timestamp jest starszy niż kilka minut, aby zabezpieczyć się przed powtórzeniem przechwyconego żądania. Zonos sam nie wymusza okna dostarczenia, więc ta kontrola należy do ciebie.
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}

Uwaga: Jeśli skonfigurowałeś niestandardowe nagłówki dla swojego webhooka, są one również dołączane dosłownie do każdego żądania obok zonos-signature.

Wyświetl dzienniki webhooków 

Aby wyświetlić dzienniki webhooków za pośrednictwem 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

Czy ta strona była pomocna?

Uzyskaj wsparcie·Dokumenty prawne·© 2026 Zonos
Na tej stronie:
  • Słuchaj zdarzeń za pośrednictwem webhooków
  • Typy webhooków
  • Tworzenie webhooków
  • Edytuj szczegóły webhooka
  • Weryfikacja podpisów webhooków
  • Wyświetl dzienniki webhooków