Kom i gang med webhooks

Webhooks forteller dine egne systemer med en gang noe skjer i Zippendo, for eksempel når en sending sendes eller en sporingsstatus endres, slik at nettbutikken eller ERP-systemet ditt holder seg oppdatert uten å spørre API-et om og om igjen.

Webhooks er inkludert i alle planer.

1. Legg til en webhook

Åpne Webhooks

I app.zippendo.com åpner du organisasjonsmenyen nederst i sidemenyen, klikker Administrer, og deretter Webhooks.

Opprett webhooken

Klikk Legg til webhook. Skriv inn et Navn og din Endepunkt-URL, kryss av for Hendelser du vil ha, og klikk Opprett webhook.

Hent signeringshemmeligheten

Zippendo oppretter en signeringshemmelighet for hver webhook. Appen viser den ikke: les den med API-et fra GET /orgs/{orgId}/webhooks/{webhookId}, eller fra svaret når du oppretter webhooken via API-et med POST /orgs/{orgId}/webhooks. Lagre den på serveren din og verifiser signaturen ved hver levering.

2. Hendelser

Hendelse	Sendes når
`shipment.created`	En sending opprettes
`shipment.updated`	En sending endres
`shipment.dispatched`	En sending sendes til transportøren
`shipment.cancelled`	En sending slettes
`shipment.error`	Det mislykkes å sende en sending til transportøren
`order.created`	En ordre opprettes i appen eller via API-et
`order.updated`	En ordre endres i appen eller via API-et
`order.cancelled`	En ordre slettes i appen eller via API-et
`tracking.updated`	En pakke får en ny sporingshendelse

Ordrer som importeres fra en ordrekanal, sender ikke order.*-hendelser. Send test på en webhook sender en webhook.test-hendelse til det ene endepunktet.

3. Leveringskontrakten

Hver levering er en HTTPS-POST med en JSON-kropp på formen { "event", "timestamp", "brandId", "data" } og tre topptekster:

Topptekst	Verdi
`X-Webhook-Signature`	HMAC-SHA256 av den rå forespørselskroppen, hex-kodet, med webhookens signeringshemmelighet som nøkkel
`X-Webhook-Event`	Hendelsesnavnet, for eksempel `shipment.dispatched`
`X-Webhook-Id`	Unik leverings-ID. En levering som prøves på nytt, beholder den samme ID-en.

En levering får tidsavbrudd etter 10 sekunder. Alle andre svar enn 2xx, eller et tidsavbrudd, regnes som en feil, og Zippendo prøver igjen med en økende pause mellom forsøkene: opptil 5 forsøk totalt. Hvert forsøk, mislykket eller ikke, vises i webhookens Leveringslogg under Webhooks.

4. Håndter leveringer

Endepunktet ditt bør:

Svare med en 2xx-status raskt, og gjøre tungt arbeid i bakgrunnen
Bruke HTTPS
Verifisere signaturen før det stoler på kroppen
Håndtere nye forsøk trygt: bruk X-Webhook-Id for å hoppe over en levering 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 utvikler

Bruk en tunnel (for eksempel ngrok) for å gi utviklingsserveren din en offentlig HTTPS-adresse, som https://your-tunnel.ngrok.io/webhooks/zippendo. Pek en testwebhook mot den og klikk Send test.

Start

Hurtigstarter

Sendingsflyt

Tilkoblinger

Drift

Organisasjon og konto

Kom i gang med webhooks

1. Legg til en webhook

2. Hendelser

3. Leveringskontrakten

4. Håndter leveringer

5. Test mens du utvikler

Neste steg

Veiledning for webhooks

REST API

​1. Legg til en webhook

​2. Hendelser

​3. Leveringskontrakten

​4. Håndter leveringer

​5. Test mens du utvikler

​Neste steg

Veiledning for webhooks

REST API

1. Legg til en webhook

2. Hendelser

3. Leveringskontrakten

4. Håndter leveringer

5. Test mens du utvikler

Neste steg