DOCS
StartpaginaVoor logistieke dienstverleners Webhooks

Luister naar events met webhooks

Ontvang real-time eventmeldingen voor uw Zonos-integratie.

Webhooks laten Zonos uw externe systemen proactief informeren wanneer bepaalde events plaatsvinden. Bij het geabonneerde event stuurt Zonos een HTTP POST naar uw webhook-URL. De request body bevat eventdetails zodat uw systeem het programmatisch kan afhandelen.

Webhooks zijn nuttig om Zonos te integreren met andere platforms, workflows te triggeren en data real-time gesynchroniseerd te houden. Bijvoorbeeld:

  • Werk uw orderbeheersysteem bij wanneer een order in Zonos wordt aangemaakt
  • Informeer uw fulfillment provider wanneer een zending wordt geannuleerd
  • Log statuswijzigingen van internationale orders voor auditdoeleinden

Webhooktypes 

Alle beschikbare webhooktypes staan in de WebhookType-enum. Voorbeeldpayloads staan in onze Event Types-gids.

Webhooks aanmaken 

Om een webhook via de API aan te maken:

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}

Belangrijk: Bewaar de secret-waarde wanneer u de webhook aanmaakt — deze wordt alleen hier geretourneerd en u hebt hem nodig om webhookhandtekeningen te verifiëren. Zie Webhookhandtekeningen verifiëren hieronder.

Webhookdetails bewerken 

Om een bestaande webhook via de API te bewerken:

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

Webhookhandtekeningen verifiëren 

Elk webhookverzoek dat Zonos verstuurt bevat een zonos-signature-header, zodat u kunt bevestigen dat het verzoek daadwerkelijk van Zonos afkomstig is en dat de payload onderweg niet is gewijzigd.

De headerwaarde heeft de volgende indeling:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — het tijdstip, in Unix-epoch milliseconden, waarop het verzoek is ondertekend.
  • hmac — een HMAC-SHA256-handtekening van de ruwe JSON-request body, berekend met de secret van uw webhook als key en Base64-gecodeerd.

Om een verzoek te verifiëren:

  1. Haal de waarden timestamp en hmac uit de zonos-signature-header.
  2. Bereken uw eigen HMAC-SHA256-handtekening over de ruwe, ongeparste request body, met de secret die u ontving bij het aanmaken van de webhook.
  3. Vergelijk uw berekende handtekening met de hmac-waarde met behulp van een constant-time vergelijking en wijs het verzoek af als ze niet overeenkomen.
  4. Wijs desgewenst verzoeken af waarvan de timestamp ouder is dan een paar minuten, om replay van een onderschept verzoek te voorkomen. Zonos legt zelf geen bezorgvenster op, dus deze controle is aan u.
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}

Opmerking: Als u aangepaste headers voor uw webhook hebt geconfigureerd, worden deze ook letterlijk meegestuurd bij elk verzoek, naast zonos-signature.

Webhooklogs bekijken 

Om webhooklogs via de API te bekijken:

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

Was deze pagina nuttig?

Krijg ondersteuning·Juridische documenten·© 2026 Zonos
Op deze pagina:
  • Luister naar events met webhooks
  • Webhooktypes
  • Webhooks aanmaken
  • Webhookdetails bewerken
  • Webhookhandtekeningen verifiëren
  • Webhooklogs bekijken