Webhookien pikaopas

Webhookit kertovat omille järjestelmillesi heti, kun Zippendossa tapahtuu jotain, esimerkiksi kun lähetys lähtee tai seurannan tila muuttuu. Näin verkkokauppasi tai ERP pysyy ajan tasalla ilman, että API:lta tarvitsee kysellä yhä uudelleen.

Webhookit sisältyvät jokaiseen pakettiin.

1. Lisää webhook

Avaa Webhookit

Avaa app.zippendo.com-palvelussa organisaatiovalikko sivupalkin alareunasta, napsauta Hallitse ja sitten Webhookit.

Luo webhook

Napsauta Lisää webhook. Kirjoita Nimi ja Päätepisteen URL, valitse haluamasi Tapahtumat ja napsauta Luo webhook.

Hae allekirjoitussalaisuus

Zippendo luo jokaiselle webhookille allekirjoitussalaisuuden. Sovellus ei näytä sitä: lue se API:n kautta osoitteesta GET /orgs/{orgId}/webhooks/{webhookId} tai vastauksesta, kun luot webhookin API:n kautta kutsulla POST /orgs/{orgId}/webhooks. Tallenna se palvelimellesi ja tarkista allekirjoitus jokaisesta toimituksesta.

2. Tapahtumat

Tapahtuma	Lähetetään, kun
`shipment.created`	Lähetys luodaan
`shipment.updated`	Lähetystä muutetaan
`shipment.dispatched`	Lähetys lähetetään kuljetusyhtiölle
`shipment.cancelled`	Lähetys poistetaan
`shipment.error`	Lähetyksen lähettäminen kuljetusyhtiölle epäonnistuu
`order.created`	Tilaus luodaan sovelluksessa tai API:n kautta
`order.updated`	Tilausta muutetaan sovelluksessa tai API:n kautta
`order.cancelled`	Tilaus poistetaan sovelluksessa tai API:n kautta
`tracking.updated`	Paketille tulee uusi seurantatapahtuma

Myyntikanavasta tuoduista tilauksista ei lähetetä order.*-tapahtumia. Webhookin Lähetä testi lähettää webhook.test-tapahtuman kyseiselle päätepisteelle.

3. Toimitussopimus

Jokainen toimitus on HTTPS-POST JSON-sisällöllä, jonka muoto on { "event", "timestamp", "brandId", "data" }, ja siinä on kolme otsikkoa:

Otsikko	Arvo
`X-Webhook-Signature`	Pyynnön raakasisällön HMAC-SHA256 heksakoodattuna, avaimena webhookin allekirjoitussalaisuus
`X-Webhook-Event`	Tapahtuman nimi, esimerkiksi `shipment.dispatched`
`X-Webhook-Id`	Toimituksen yksilöivä ID. Uudelleen yritetty toimitus säilyttää saman ID:n.

Toimitus aikakatkaistaan 10 sekunnin jälkeen. Mikä tahansa muu vastaus kuin 2xx tai aikakatkaisu lasketaan epäonnistumiseksi, ja Zippendo yrittää uudelleen kasvavin väliajoin: yhteensä enintään 5 yritystä. Jokainen yritys, onnistunut tai ei, näkyy webhookin Toimituslokissa kohdassa Webhookit.

4. Käsittele toimitukset

Päätepisteesi tulisi:

Vastata 2xx-tilalla nopeasti ja tehdä raskas työ taustalla
Käyttää HTTPS-yhteyttä
Tarkistaa allekirjoitus ennen kuin luottaa sisältöön
Käsitellä uudelleenyritykset turvallisesti: käytä X-Webhook-Id-tunnusta ohittaaksesi toimituksen, jonka olet jo käsitellyt

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. Testaa kehityksen aikana

Käytä tunnelia (esimerkiksi ngrok), jotta kehityspalvelimellesi saadaan julkinen HTTPS-osoite, kuten https://your-tunnel.ngrok.io/webhooks/zippendo. Osoita testiwebhook siihen ja napsauta Lähetä testi.

Aloitus

Pika-aloitukset

Toimitusprosessi

Yhteydet

Toiminnot

Organisaatio ja tili

Webhookien pikaopas

1. Lisää webhook

2. Tapahtumat

3. Toimitussopimus

4. Käsittele toimitukset

5. Testaa kehityksen aikana

Seuraavat vaiheet

Webhook-opas

REST API

​1. Lisää webhook

​2. Tapahtumat

​3. Toimitussopimus

​4. Käsittele toimitukset

​5. Testaa kehityksen aikana

​Seuraavat vaiheet

Webhook-opas

REST API

1. Lisää webhook

2. Tapahtumat

3. Toimitussopimus

4. Käsittele toimitukset

5. Testaa kehityksen aikana

Seuraavat vaiheet