> ## Documentation Index
> Fetch the complete documentation index at: https://www.zippendo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhookien pikaopas

> Vastaanota Zippendon reaaliaikaisia tapahtumia palvelimellasi, kun lähetykset, tilaukset ja seuranta muuttuvat.

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.

<Note>
  Webhookit sisältyvät jokaiseen pakettiin.
</Note>

## 1. Lisää webhook

<Steps>
  <Step title="Avaa Webhookit">
    Avaa [app.zippendo.com](https://app.zippendo.com)-palvelussa organisaatiovalikko sivupalkin alareunasta, napsauta **Hallitse** ja sitten **Webhookit**.
  </Step>

  <Step title="Luo webhook">
    Napsauta **Lisää webhook**. Kirjoita **Nimi** ja **Päätepisteen URL**, valitse haluamasi **Tapahtumat** ja napsauta **Luo webhook**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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 **Toimitusloki**ssa 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

```javascript theme={null}
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**.

## Seuraavat vaiheet

<CardGroup cols={2}>
  <Card title="Webhook-opas" icon="book-open" href="/docs/fi/settings/webhooks">
    Muokkaa, keskeytä ja poista webhookeja sekä lue toimitusloki.
  </Card>

  <Card title="REST API" icon="terminal" href="/docs/fi/quickstarts/rest-api">
    Yhdistä webhookit API-kutsuihin, kun tarvitset tietoja pyynnöstä.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.