DOCS
HjemTil logistikudbydere Webhooks

Lyt til begivenheder med webhooks

Få notifikationer om begivenheder i realtid til din Zonos-integration.

Webhooks giver Zonos mulighed for proaktivt at underrette dine eksterne systemer, når bestemte begivenheder finder sted. Når den abonnerede begivenhed indtræffer, sender Zonos en HTTP POST-anmodning til den webhook-URL, du angiver. Anmodningens brødtekst indeholder begivenhedsdetaljerne, så dit system kan håndtere begivenheden programmatisk.

Webhooks er nyttige til at integrere Zonos med andre platforme, udløse automatiserede workflows og holde data synkroniseret på tværs af systemer i realtid. Du kan for eksempel bruge webhooks til at:

  • Opdatere dit ordrestyringssystem, når en ordre oprettes i Zonos
  • Underrette din opfyldelsesudbyder, når en forsendelse annulleres
  • Logge statusændringer for internationale ordrer til revisionsformål

Webhook-typer 

Alle tilgængelige webhook-typer findes i enum WebhookType. Eksempel-payloads for hver type findes i vores guide til Begivenhedstyper.

Oprettelse af webhooks 

For at oprette en webhook via 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}

Vigtigt: Gem værdien for secret, når du opretter webhooken — den returneres kun her, og du får brug for den til at verificere webhook-signaturer. Se Verificering af webhook-signaturer nedenfor.

Rediger webhook-detaljer 

For at redigere en eksisterende webhook via API:

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

Verificering af webhook-signaturer 

Hver webhook-anmodning, som Zonos sender, indeholder en zonos-signature-header, så du kan bekræfte, at anmodningen faktisk kom fra Zonos, og at indholdet ikke er blevet ændret undervejs.

Header-værdien har følgende format:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — tidspunktet, i Unix-epoke-millisekunder, hvor anmodningen blev signeret.
  • hmac — en HMAC-SHA256-signatur af den rå JSON-anmodningstekst, beregnet med din webhooks secret som nøgle og Base64-kodet.

Sådan verificerer du en anmodning:

  1. Udtræk værdierne for timestamp og hmac fra zonos-signature-headeren.
  2. Beregn din egen HMAC-SHA256-signatur over den rå, ikke-parsede anmodningstekst ved hjælp af den secret, du modtog, da du oprettede webhooken.
  3. Sammenlign din beregnede signatur med hmac-værdien ved hjælp af en konstant-tids-sammenligning, og afvis anmodningen, hvis de ikke stemmer overens.
  4. Du kan eventuelt afvise anmodninger, hvor timestamp er ældre end nogle få minutter, for at beskytte mod gentagelse (replay) af en opsnappet anmodning. Zonos håndhæver ikke selv et leveringsvindue, så dette tjek er op til dig.
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}

Bemærk: Hvis du har konfigureret brugerdefinerede headers til din webhook, er disse også inkluderet uændret i hver anmodning sammen med zonos-signature.

Vis webhook-logfiler 

For at se webhook-logfiler via 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

Var denne side nyttig?

Få support·Juridiske dokumenter·© 2026 Zonos
På denne side:
  • Lyt til begivenheder med webhooks
  • Webhook-typer
  • Oprettelse af webhooks
  • Rediger webhook-detaljer
  • Verificering af webhook-signaturer
  • Vis webhook-logfiler