Webhooks-quickstart

Webhooks fortæller dine egne systemer med det samme, når noget sker i Zippendo, for eksempel når en forsendelse sendes, eller en trackingstatus ændres, så din webshop eller dit ERP holder sig opdateret uden at spørge API’et igen og igen.

Webhooks er inkluderet i alle planer.

1. Tilføj en webhook

Åbn Webhooks

Åbn organisationsmenuen nederst i sidebjælken i app.zippendo.com, klik på Administrer og derefter på Webhooks.

Opret webhooken

Klik på Tilføj webhook. Skriv et Navn og din Endpoint-URL, sæt kryds ved de Hændelser, du vil have, og klik på Opret webhook.

Hent signeringshemmeligheden

Zippendo opretter en signeringshemmelighed til hver webhook. Appen viser den ikke: læs den med API’et fra GET /orgs/{orgId}/webhooks/{webhookId}, eller fra svaret, når du opretter webhooken gennem API’et med POST /orgs/{orgId}/webhooks. Gem den på din server, og bekræft signaturen ved hver levering.

2. Hændelser

Hændelse	Sendes, når
`shipment.created`	En forsendelse oprettes
`shipment.updated`	En forsendelse ændres
`shipment.dispatched`	En forsendelse sendes til transportøren
`shipment.cancelled`	En forsendelse slettes
`shipment.error`	Afsendelsen af en forsendelse til transportøren mislykkes
`order.created`	En ordre oprettes i appen eller gennem API’et
`order.updated`	En ordre ændres i appen eller gennem API’et
`order.cancelled`	En ordre slettes i appen eller gennem API’et
`tracking.updated`	En pakke får en ny trackinghændelse

Ordrer, der importeres fra en ordrekanal, sender ikke order.*-hændelser. Send test på en webhook sender en webhook.test-hændelse til det ene endpoint.

3. Leveringskontrakten

Hver levering er en HTTPS-POST med en JSON-body i formen { "event", "timestamp", "brandId", "data" } og tre headers:

Header	Værdi
`X-Webhook-Signature`	HMAC-SHA256 af den rå request-body, hex-kodet, med webhookens signeringshemmelighed som nøgle
`X-Webhook-Event`	Hændelsens navn, for eksempel `shipment.dispatched`
`X-Webhook-Id`	Unikt leverings-ID. En gentaget levering beholder samme ID.

En levering timer ud efter 10 sekunder. Ethvert andet svar end 2xx, eller en timeout, tæller som en fejl, og Zippendo prøver igen med en voksende pause imellem: op til 5 forsøg i alt. Hvert forsøg, uanset om det mislykkes eller ej, står i webhookens Leveringslog under Webhooks.

4. Håndter leveringer

Dit endpoint bør:

Svare hurtigt med en 2xx-status og lave tungt arbejde i baggrunden
Bruge HTTPS
Bekræfte signaturen, før det stoler på body’en
Håndtere gentagelser sikkert: brug X-Webhook-Id til at springe en levering over, du allerede har behandlet

import crypto from "node:crypto"

export async function POST(request) {
  const body = await request.text()

  const expected = crypto.createHmac("sha256", process.env.ZIPPENDO_WEBHOOK_SECRET)
    .update(body)
    .digest("hex")
  const signature = request.headers.get("x-webhook-signature") ?? ""
  const valid = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  if (!valid) return new Response("invalid signature", { status: 401 })

  queueMicrotask(() => processZippendoEvent(JSON.parse(body)))
  return new Response("ok", { status: 200 })
}

5. Test, mens du udvikler

Brug en tunnel (for eksempel ngrok) til at give din udviklingsserver en offentlig HTTPS-adresse, såsom https://your-tunnel.ngrok.io/webhooks/zippendo. Peg en test-webhook på den, og klik på Send test.

Start

Quickstarts

Forsendelsesflow

Forbindelser

Drift

Organisation og konto

Webhooks-quickstart

1. Tilføj en webhook

2. Hændelser

3. Leveringskontrakten

4. Håndter leveringer

5. Test, mens du udvikler

Næste skridt

Webhooks-guide

REST API

​1. Tilføj en webhook

​2. Hændelser

​3. Leveringskontrakten

​4. Håndter leveringer

​5. Test, mens du udvikler

​Næste skridt

Webhooks-guide

REST API

1. Tilføj en webhook

2. Hændelser

3. Leveringskontrakten

4. Håndter leveringer

5. Test, mens du udvikler

Næste skridt