DOCS
StartseiteFür Logistikdienstleister Webhooks

Hören Sie sich Ereignisse mit Webhooks an

Erhalten Sie Echtzeit-Ereignisbenachrichtigungen für Ihre Zonos-Integration.

Webhooks bieten Zonos die Möglichkeit, Ihre externen Systeme proaktiv zu benachrichtigen, wenn bestimmte Ereignisse stattfinden. Wenn das abonnierte Ereignis eintritt, sendet Zonos eine HTTP-POST-Anfrage an die von Ihnen angegebene Webhook-URL. Der Anforderungstext enthält die Ereignisdetails, sodass Ihr System das Ereignis programmgesteuert verarbeiten kann.

Webhooks sind nützlich, um Zonos mit anderen Plattformen zu integrieren, automatisierte Workflows auszulösen und Daten systemübergreifend in Echtzeit zu synchronisieren. Sie könnten Webhooks beispielsweise verwenden, um:

  • Ihr Auftragsverwaltungssystem zu aktualisieren, wenn eine Bestellung in Zonos erstellt wird
  • Ihren Fulfillment-Anbieter zu benachrichtigen, wenn eine Sendung storniert wird
  • Statusänderungen internationaler Bestellungen zu Prüfzwecken zu protokollieren

Webhook-Typen 

Alle verfügbaren Webhook-Typen sind in der WebhookType-Enumeration enthalten. Beispielnutzlasten für jeden finden Sie in unserem Ereignistypen-Leitfaden.

Webhooks erstellen 

So erstellen Sie einen Webhook über die 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}

Wichtig: Speichern Sie den Wert secret, wenn Sie den Webhook erstellen – er wird nur an dieser Stelle zurückgegeben, und Sie benötigen ihn, um Webhook-Signaturen zu überprüfen. Siehe Überprüfen von Webhook-Signaturen weiter unten.

Webhook-Details bearbeiten 

So bearbeiten Sie einen vorhandenen Webhook über die API:

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

Überprüfen von Webhook-Signaturen 

Jede von Zonos gesendete Webhook-Anfrage enthält einen zonos-signature-Header, mit dem Sie bestätigen können, dass die Anfrage tatsächlich von Zonos stammt und dass die Nutzlast während der Übertragung nicht verändert wurde.

Der Header-Wert hat das folgende Format:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — der Zeitpunkt, zu dem die Anfrage signiert wurde, in Unix-Epochen-Millisekunden.
  • hmac — eine HMAC-SHA256-Signatur des rohen JSON-Anfragetexts, berechnet mit dem Secret Ihres Webhooks als Schlüssel und Base64-codiert.

So überprüfen Sie eine Anfrage:

  1. Extrahieren Sie die Werte timestamp und hmac aus dem zonos-signature-Header.
  2. Berechnen Sie Ihre eigene HMAC-SHA256-Signatur über den rohen, nicht geparsten Anfragetext, unter Verwendung des Secrets, das Sie beim Erstellen des Webhooks erhalten haben.
  3. Vergleichen Sie Ihre berechnete Signatur mit dem Wert hmac anhand eines zeitkonstanten Vergleichs und lehnen Sie die Anfrage ab, wenn sie nicht übereinstimmen.
  4. Lehnen Sie optional Anfragen ab, bei denen timestamp älter als einige Minuten ist, um sich vor der Wiederholung einer abgefangenen Anfrage zu schützen. Zonos erzwingt selbst kein Zustellfenster, daher liegt diese Prüfung bei Ihnen.
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}

Hinweis: Wenn Sie benutzerdefinierte Header für Ihren Webhook konfiguriert haben, werden diese ebenfalls unverändert bei jeder Anfrage neben zonos-signature mitgesendet.

Webhook-Protokolle anzeigen 

So zeigen Sie Webhook-Protokolle über die API an:

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

War diese Seite hilfreich?

Holen Sie sich Unterstützung·Rechtsdokumente·© 2026 Zonos
Auf dieser Seite:
  • Hören Sie sich Ereignisse mit Webhooks an
  • Webhook-Typen
  • Webhooks erstellen
  • Webhook-Details bearbeiten
  • Überprüfen von Webhook-Signaturen
  • Webhook-Protokolle anzeigen