---
title: "Digitaalisten tuotepassien automatisointi webhookien avulla — qr3.app Blog"
description: "Digitaalinen tuotepassi ei ole staattinen sivu — jokainen skannaus on tapahtuma, jonka varaan voit rakentaa. Reagoi qr.scanned-tapahtumaan analytiikkaa, uudelleentilauksia ja takaisinvetomerkintöjä varten, pidä passin tiedot ajan tasalla ERP-järjestelmästäsi ja varmenna jokainen hyötykuorma HMAC-SHA256:lla. Kehittäjätason opas koodiesimerkkeineen."
canonical: "https://qr3.app/fi/blog/dpp-webhooks-automation/"
lang: "fi"
robots: "index,follow,max-image-preview:large,max-snippet:-1"
---

# Digitaalisten tuotepassien automatisointi webhookien avulla — qr3.app Blog

> Digitaalinen tuotepassi ei ole staattinen sivu — jokainen skannaus on tapahtuma, jonka varaan voit rakentaa. Reagoi qr.scanned-tapahtumaan analytiikkaa, uudelleentilauksia ja takaisinvetomerkintöjä varten, pidä passin tiedot ajan tasalla ERP-järjestelmästäsi ja varmenna jokainen hyötykuorma HMAC-SHA256:lla. Kehittäjätason opas koodiesimerkkeineen.

Canonical: <https://qr3.app/fi/blog/dpp-webhooks-automation/>

[← Blogi](/fi/blog/) [Tutoriaalit](/fi/blog/category/tutorials/)

30. toukokuuta 2026 5 min lukuaika [Tutoriaalit](/fi/blog/category/tutorials/) [dpp](/fi/blog/tag/dpp/)[webhooks](/fi/blog/tag/webhooks/)[automation](/fi/blog/tag/automation/)[qr-scanned](/fi/blog/tag/qr-scanned/)[sdk](/fi/blog/tag/sdk/)

# Digitaalisten tuotepassien automatisointi webhookien avulla

Digitaalinen tuotepassi ei ole staattinen sivu — jokainen skannaus on tapahtuma, jonka varaan voit rakentaa. Reagoi qr.scanned-tapahtumaan analytiikkaa, uudelleentilauksia ja takaisinvetomerkintöjä varten, pidä passin tiedot ajan tasalla ERP-järjestelmästäsi ja varmenna jokainen hyötykuorma HMAC-SHA256:lla. Kehittäjätason opas koodiesimerkkeineen.

kirjoittanut **QR3 Redaktion**

![Digitaalisten tuotepassien automatisointi webhookien avulla](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-webhooks-automation/hero.png)

Useimmat tiimit kohtelevat digitaalista tuotepassia sivuna: luot sen, tulostat QR-koodin ja unohdat sen. Näin hyödyllisin signaali jää käyttämättä. Joka kerta, kun joku skannaa tuotteen QR-koodin, kyseessä on **tapahtuma** — todellinen ihminen, todellisessa maassa, pitelemässä todellista yksikköä, todellisella hetkellä. Kytke nämä tapahtumat osaksi järjestelmäpinoasi, niin passi lakkaa olemasta staattinen sivu ja muuttuu automaatioputken käyttöliittymäksi. Tässä oppaassa näytetään, kuinka tilataan `qr.scanned`, varmennetaan jokainen hyötykuorma ja muutetaan skannaukset ja päivitykset oikeiksi työnkuluiksi qr3-SDK:n avulla.

## Miksi DPP on tapahtumalähde, ei staattinen sivu

Passin arvo ei ole sivu, jonka kuluttaja näkee kerran. Se on sitä ympäröivä vuorovaikutusten virta: skannaukset kentällä, tietomuutokset ERP-järjestelmästäsi, elinkaaren siirtymät. Jokainen näistä on jotain, johon järjestelmäsi voivat reagoida reaaliajassa.

Webhookit kääntävät tavanomaisen kyselymallin päälaelleen. Sen sijaan, että kysyisit *"onko mitään tapahtunut?"* ajastimen avulla, qr3 kutsuu **sinua** sillä hetkellä, kun jotain tapahtuu. Alustan lähettämiin tapahtumatyyppeihin kuuluvat `qr.scanned` sekä `qr.created`, `qr.updated` ja `qr.deleted` elinkaaren muutoksia varten. Tapahtuma, jota useimmat tiimit hyödyntävät liian vähän, on `qr.scanned`: se laukeaa, kun kuluttaja, asentaja tai tullivirkailija todella skannaa tuotteen kentällä.

`qr.scanned`-hyötykuorma kuljettaa toiminnan kannalta tarvitsemasi kontekstin — mukaan lukien skannauksen **maan** ja **dpp/code id** -tunnisteen, joka kertoo, mikä yksikkö skannattiin. Se riittää ohjaamaan analytiikkaa, täydennystä ja takaisinvetologiikkaa ilman ihmistä silmukassa.

## qr.scanned-tapahtuman tilaaminen

Osoita webhook-päätepiste palveluusi ja käsittele tapahtuma. Varmista allekirjoitus raakahyötykuormaa vasten ennen kuin jäsennät sen:

```
import express from "express";
import { createHmac, timingSafeEqual } from "crypto";

const app = express();
const secret = process.env.QR3_WEBHOOK_SECRET!;

// Recompute the HMAC over the exact bytes qr3 signed and compare in constant time.
function verify(raw: Buffer, header: string | undefined): boolean {
  const expected = createHmac("sha256", secret).update(raw).digest("hex");
  const expectedBytes = Buffer.from(`sha256=${expected}`);
  const receivedBytes = Buffer.from(header ?? "");
  return (
    expectedBytes.length === receivedBytes.length &&
    timingSafeEqual(expectedBytes, receivedBytes)
  );
}

// Use the raw body so the signature matches the exact bytes qr3 signed.
app.post("/webhooks/qr3", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.headers["x-qr3-signature"] as string)) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString("utf8"));

  if (event.type === "qr.scanned") {
    // event payload includes fields like the scan country and the dpp/code id
    handleScan(event);
  }

  res.sendStatus(200);
});
```

Käsittelijä on tarkoituksella ohut: varmenna, haaraudu `event.type`-arvon mukaan ja kuittaa nopeasti `200`-koodilla. Tee raskas työ (analytiikkakirjoitukset, ERP-kutsut) asynkronisesti, jotta hidas alavirran palvelu ei koskaan estä kuittausta.

## Allekirjoitusten varmentaminen (HMAC-SHA256) — tee tämä aina

Webhook-päätepiste on julkinen URL. Kuka tahansa, joka sen löytää, voi lähettää siihen POST-pyynnön. Jos luotat hyötykuormaan tarkistamatta, kuka sen lähetti, hyökkääjä voi väärentää "skannauksia", laukaista valheellisia uudelleentilauksia tai sytyttää vääriä takaisinvetomerkintöjä. **Varmenna allekirjoitus aina ennen kuin toimit hyötykuorman perusteella.**

qr3 allekirjoittaa jokaisen webhookin **HMAC-SHA256:lla** raa'an pyynnön rungon yli käyttäen päätepisteesi salaisuutta. Allekirjoitus saapuu `X-QR3-Signature`-pyyntöotsikossa muodossa `sha256=` seurattuna heksadesimaalitiivisteellä. Laske HMAC uudelleen samojen tavujen yli ja vertaa niitä kahta vakiossa ajassa; jos ne eroavat, hylkää pyyntö:

```
app.post("/webhooks/qr3", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.headers["x-qr3-signature"] as string)) {
    // signature mismatch → not from qr3 (or body was altered in transit)
    return res.sendStatus(401);
  }
  process(JSON.parse(req.body.toString("utf8")));
  res.sendStatus(200);
});
```

Kolme sääntöä, jotka pitävät tämän rehellisenä:

- **Varmenna raakatavuja vastaan.** JSON:n uudelleenserialisointi voi järjestää avaimet uudelleen ja muuttaa välilyöntejä, mikä rikkoo HMAC:n. Kaappaa raakaruoko (yllä, `express.raw`).

- **Pidä salaisuus salassa.** Se sijaitsee ympäristössäsi, ei koskaan asiakaskoodissa tai repositoriossa.

- **Epäonnistu suljettuna.** Ei kelvollista allekirjoitusta → `401`, ei sivuvaikutuksia. Älä koskaan "käsittele silti", jos täsmäys epäonnistuu.

## Mallit: analytiikka / uudelleentilaus / takaisinveto

Kun luotat tapahtumaan, kourallinen malleja kattaa suurimman osan siitä, mitä tiimit haluavat:

```
function handleScan(event: { type: string; data: { country?: string; dpp_id?: string } }) {
  // 1) Analytics — where and how often are products scanned?
  metrics.increment("dpp.scan", { country: event.data.country });

  // 2) Re-order — a scan can signal consumption or field activity
  if (event.data.country) maybeReplenish(event.data.dpp_id, event.data.country);

  // 3) Recall flag — scans of a flagged unit alert your team
  if (isRecalled(event.data.dpp_id)) alertRecall(event.data.dpp_id, event.data.country);
}
```

- **Analytiikka:** kokoa skannaukset maittain ja yksiköittäin nähdäksesi todellisen sitoutumisen — mitkä markkinat oikeasti skannaavat ja mitkä tuotenimikkeet saavat eniten myynnin jälkeistä vuorovaikutusta.

- **Uudelleentilaus / täydennys:** skannausten ryöppy alueella voi syöttää kysyntäsignaaleja tai laukaista täydennystyönkulkuja ERP-järjestelmässäsi.

- **Takaisinveto / turvallisuus:** jos yksikkö on takaisinvedossa, skannaus on tilaisuus tavoittaa se, joka sitä pitelee — hälytä tiimisi tai nosta ilmoitus esiin itse passissa.

Mikään näistä ei tarvitse kyselyä tai öistä eräajoa. Ne tapahtuvat sillä hetkellä, kun tuote skannataan.

## Tietojen pitäminen ajan tasalla client.dpp.update-metodilla

Skannauksiin reagoiminen on puolet silmukasta; toinen puoli on itse passin pitäminen tarkkana. Sääntelyt, kuten **ESPR (EU 2024/1781)** ja **akkuasetus (EU 2023/1542)**, edellyttävät, että passin tiedot heijastavat todellisuutta tuotteen elinkaaren ajan — uudelleenlaskettu hiilijalanjälki, päivitetyt korjausohjeet, saavutetut kierrätysmateriaalitavoitteet.

Ohjaa nämä päivitykset päärekisteristä. Kun arvo muuttuu ERP-järjestelmässäsi, työnnä se passiin:

```
import { QR3 } from "@qr3/sdk";

const client = new QR3({ apiKey: process.env.QR3_API_KEY! });

// GTIN and serial are immutable; data fields are updatable.
await client.dpp.update(dppId, {
  battery_data: { carbon_footprint_kg: 58, recycled_content_pct: 16 },
});
```

Koska QR-koodi koodaa vakaan resolver-URL:n (`https://qr3.app/dpp/{gtin}/{serial}`, lisää `?format=jsonld` JSON-LD:tä varten), sinun ei koskaan tarvitse tulostaa nimilappua uudelleen tietojen muuttamiseksi. Identiteetti pysyy kiinteänä; sen takana oleva sisältö pysyy ajan tasalla. Yhdistä tämä `qr.updated`-tapahtumaan, niin voit lähettää ilmoituksen aina, kun passi muuttuu — sulkien silmukan ERP-järjestelmäsi, passin ja kenen tahansa alavirrassa seuraavan välillä.

## Tapahtumataulukko: tapahtuma → mitä automatisoida

| Tapahtuma | Laukeaa, kun | Mitä automatisoida |
| --- | --- | --- |
| `qr.scanned` | Tuotteen QR-koodi skannataan kentällä | Analytiikka maittain, täydennyssignaalit, takaisinvetohälytykset |
| `qr.created` | Uusi passi luodaan | Indeksoi se, synkronoi PIM/ERP:hen, ilmoita luettelotiimille |
| `qr.updated` | Passin tiedot muuttuvat | Välimuistita julkinen sivu uudelleen, lähetä muutosilmoitukset |
| `qr.deleted` | Passi poistetaan | Merkitse sisäiset tietueet poistetuiksi, peru alavirran viittaukset |

Aloita `qr.scanned`-tapahtumasta sitoutumisen ja kenttäsignaalien osalta; lisää elinkaaritapahtumat sitä mukaa, kun synkronoit passeja laajempiin järjestelmiisi.

## UKK

**Pitääkö minun varmentaa allekirjoitus, jos päätepisteeni URL on salainen?**
Kyllä. URL ei ole salaisuus — se vuotaa lokeihin, välityspalvelimiin ja selaimen historiaan. `X-QR3-Signature`-HMAC-allekirjoituksen tarkistaminen raakaa runkoa vasten on ainoa asia, joka todistaa, että hyötykuorma todella tuli qr3:sta.

**Mitä tapahtuu, jos päätepisteeni on alhaalla, kun tapahtuma laukeaa?**
Kuittaa nopeasti `200`-koodilla heti varmennettuasi ja tee hidas työ asynkronisesti, jotta hetkelliset alavirran ongelmat eivät koskaan pysäytä vastausta. Pidä yllä omaa idempotenssia `dpp/code id` -tunnisteen perusteella, jotta uudelleen toimitettua viestiä ei lasketa kahdesti.

**Voinko päivittää GTIN:n tai sarjanumeron client.dpp.update-metodilla?**
En — GTIN ja sarjanumero ovat muuttumattomia; ne ovat tuotteen vakaa identiteetti. Vain tietokentät ovat päivitettävissä. Juuri tämä muuttumattomuus pitää tulostetun QR-koodin pätevänä ikuisesti.

## Lähteet

- [EU ESPR — asetus (EU) 2024/1781](https://eur-lex.europa.eu/eli/reg/2024/1781/oj)

- [EU:n akkuasetus 2023/1542](https://eur-lex.europa.eu/eli/reg/2023/1542/oj)

- [HMAC — RFC 2104](https://www.rfc-editor.org/rfc/rfc2104)

**Aloita ilmaiseksi** ja kytke ensimmäinen DPP-webhookisi: [app.qr3.app/sign-up](https://app.qr3.app/sign-up)

## Aiheeseen liittyvät artikkelit

- [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/gs1-resolver-test-suite-dpp-links/hero.png) Tutoriaalit GS1 Resolver Test Suite: DPP-linkkien luotettava tarkistus ennen käyttöönottoa Vakaa GS1-testisarja mahdollistaa Resolver 1.2:n tarkistamisen. Näin testaat uudelleenohjaukset, linkkijoukot, CORSin, kielet ja virhetilanteet ennen käyttöönottoa.](/fi/blog/gs1-resolver-test-suite-dpp-links/)
- [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-battery-passport-2027-20260715/hero.png) Toimialauutiset BatteryPass-Ready käynnisti digitaalisen akkupassin testiympäristön BatteryPass-Ready-konsortio käynnisti 24. kesäkuuta 2026 julkisen digitaalisen akkupassin testiympäristön EU-velvoitteen lähestyessä helmikuussa 2027.](/fi/blog/dpp-battery-passport-2027-20260715/)
- [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260713/hero.png) Toimialauutiset Digitaalinen akkupassi 2027: mitä valmistajien on nyt tiedettävä Webinaarit, avoimen lähdekoodin työkalut ja uudet standardit: EU:n akkupassi etenee. Katsaus heinäkuun 2026 tilanteeseen ja avoimiin kysymyksiin helmikuuhun 2027 asti.](/fi/blog/sector-20260713/)
- [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260711/hero.png) Toimialauutiset Digitaalinen akkupassi 2026: testiympäristöt, standardit ja avoimet kysymykset Missä teollisuus on digitaalisen akkupassin käyttöönotossa? Katsaus testiympäristöihin, CEN/CENELEC-standardeihin, avoimen lähdekoodin työkaluihin ja sääntelyyn heinäkuussa 2026.](/fi/blog/sector-20260711/)

[← Kaikki artikkelit](/fi/blog/) [Aloita ilmaiseksi](https://app.qr3.app/sign-up)