Snabbstart för webhooks

Webhooks berättar för dina egna system i samma stund något händer i Zippendo, till exempel när en försändelse skickas eller en spårningsstatus ändras. På så sätt hålls din webbutik eller ditt ERP-system uppdaterat utan att du behöver fråga API:et om och om igen.

Webhooks ingår i alla planer.

1. Lägg till en webhook

Öppna Webhooks

Öppna organisationsmenyn längst ned i sidofältet i app.zippendo.com, klicka på Hantera och sedan på Webhooks.

Skapa webhooken

Klicka på Lägg till webhook. Ange ett Namn och din Endpoint URL, bocka i de Händelser du vill ha och klicka på Skapa webhook.

Hämta signeringshemligheten

Zippendo skapar en signeringshemlighet för varje webhook. Appen visar den inte: läs den via API:et med GET /orgs/{orgId}/webhooks/{webhookId}, eller i svaret när du skapar webhooken via API:et med POST /orgs/{orgId}/webhooks. Spara den på din server och verifiera signaturen vid varje leverans.

2. Händelser

Händelse	Skickas när
`shipment.created`	En försändelse skapas
`shipment.updated`	En försändelse ändras
`shipment.dispatched`	En försändelse skickas till transportören
`shipment.cancelled`	En försändelse raderas
`shipment.error`	Det går inte att skicka en försändelse till transportören
`order.created`	En order skapas i appen eller via API:et
`order.updated`	En order ändras i appen eller via API:et
`order.cancelled`	En order raderas i appen eller via API:et
`tracking.updated`	Ett paket får en ny spårningshändelse

Ordrar som importeras från en orderkanal skickar inga order.*-händelser. Skicka test på en webhook skickar en webhook.test-händelse till just den endpointen.

3. Leveransavtalet

Varje leverans är en HTTPS-POST med en JSON-body på formen { "event", "timestamp", "brandId", "data" } och tre headers:

Header	Värde
`X-Webhook-Signature`	HMAC-SHA256 av den råa request-bodyn, hex-kodad och signerad med webhookens signeringshemlighet
`X-Webhook-Event`	Händelsens namn, till exempel `shipment.dispatched`
`X-Webhook-Id`	Unikt leverans-ID. En leverans som görs om behåller samma ID.

En leverans får timeout efter 10 sekunder. Alla svar som inte är 2xx, och alla timeouts, räknas som misslyckade, och Zippendo försöker igen med en allt längre paus emellan: högst 5 försök totalt. Varje försök, lyckat eller inte, listas i webhookens Leveranslogg under Webhooks.

4. Hantera leveranser

Din endpoint bör:

Svara snabbt med en 2xx-status och göra tunga jobb i bakgrunden
Använda HTTPS
Verifiera signaturen innan den litar på bodyn
Hantera omförsök på ett säkert sätt: använd X-Webhook-Id för att hoppa över en leverans som du redan har behandlat

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. Testa medan du utvecklar

Använd en tunnel (till exempel ngrok) för att ge din utvecklingsserver en publik HTTPS-adress, till exempel https://your-tunnel.ngrok.io/webhooks/zippendo. Låt en testwebhook peka dit och klicka på Skicka test.

Start

Snabbstarter

Orderflöde

Anslutningar

Daglig drift

Organisation och konto

Snabbstart för webhooks

1. Lägg till en webhook

2. Händelser

3. Leveransavtalet

4. Hantera leveranser

5. Testa medan du utvecklar

Nästa steg

Guide till webhooks

REST API

​1. Lägg till en webhook

​2. Händelser

​3. Leveransavtalet

​4. Hantera leveranser

​5. Testa medan du utvecklar

​Nästa steg

Guide till webhooks

REST API

1. Lägg till en webhook

2. Händelser

3. Leveransavtalet

4. Hantera leveranser

5. Testa medan du utvecklar

Nästa steg