Webhookit — tapahtumailmoitukset omiin järjestelmiin

Webhookkien avulla VAREK lähettää automaattisesti tapahtumailmoituksia omiin järjestelmiisi HTTP-POST-pyyntöinä. Sen sijaan, että järjestelmäsi kyselisi rajapintaa säännöllisesti, VAREK kutsuu sinun palvelintasi aina kun jokin tärkeä tapahtuu.

Webhookit sopivat esimerkiksi:

• reklamaatiomääräaikojen automaattiseen hälyttämiseen muissa järjestelmissä,
• uusien vikojen tai reklamaatioiden kirjaamiseen ulkoiseen järjestelmään,
• tilamuutosten synkronointiin kiinteistöhallintaohjelmistoon.

:::note Vain hallituksen ylläpitäjälle. Webhookien hallinta näkyy vain taloyhtiön hallituksen ylläpitäjälle kohdassa Asetukset → Webhookit. :::

Päätepisteen luominen

1. Kirjaudu sisään hallituksen ylläpitäjänä.
2. Mene Asetukset → Webhookit.
3. Valitse Lisää päätepiste.
4. Anna päätepisteen URL — sen on oltava julkinen https://-osoite, jossa käytetään verkkotunnusta (IP-osoitteet hylätään).
5. Valitse tapahtumat, joista haluat ilmoituksen (ks. tapahtumaluettelo alla).
6. Vahvista. VAREK luo automaattisesti allekirjoitussalaisuuden (whsec_…).

:::caution Salaisuus näytetään vain kerran. Kopioi whsec_…-salaisuus välittömästi luonnin jälkeen. Sitä ei voi nähdä uudelleen. Jos salaisuus katoaa, voit paljastaa sen uudelleen kohdasta Päätepisteen tiedot → Näytä salaisuus (vain ylläpitäjä). :::

Tapahtumaluettelo

Tapahtuma	Milloin lähetetään	data-kentät
claim.deadline_approaching	Reklamaation määräaika lähestyy	claim_id, deadline_id, days_until
claim.created	Uusi reklamaatio luotu	claim_id, claim_number
claim.status_changed	Reklamaation tila muuttui	claim_id, status, previous_status
defect.created	Uusi vikailmoitus luotu	defect_id
document.uploaded	Uusi dokumentti lisätty	document_id
inspection.completed	Tarkastus merkitty valmiiksi	inspection_id, template_key
invoice.paid	Asukaslasku kuitattu maksetuksi	invoice_id, invoice_type
board_initiative.created	Hallituksen päätös tai toimeksianto luotu	initiative_id, category
board_initiative.decided	Hallituksen päätös syntyi (hyväksytty tai hylätty)	initiative_id, outcome
board_initiative.assigned	Toimeksiantoon lisättiin toimeksisaaja	initiative_id, assignee_id, target_kind, role_label
board_initiative.completed	Toimeksianto merkittiin valmiiksi	initiative_id

Toimituslomake (JSON-runko)

Jokainen toimitus on POST-pyyntö, jonka rungossa on JSON-objekti:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "claim.status_changed",
  "created_at": "2026-06-30T08:00:00Z",
  "data": {
    "claim_id": "...",
    "status": "closed",
    "previous_status": "open"
  }
}

Kenttä	Tyyppi	Kuvaus
id	UUID	Toimituksen yksilöllinen tunniste
type	merkkijono	Tapahtuman nimi (ks. tapahtumaluettelo)
created_at	ISO 8601	Tapahtuman aikaleima (UTC)
data	objekti	Tapahtuman tiedot (ID-viitteet)

Hyötykuormat ovat ohuita — ne sisältävät vain ID:t. Hae täydet tiedot REST-rajapinnasta tarvittaessa.

Allekirjoituksen varmentaminen

VAREK allekirjoittaa jokaisen toimituksen HMAC-SHA256:lla käyttämällä päätepisteen whsec_…-salaisuutta. Varmennetaan kaksi HTTP-otsikkoa:

Otsikko	Arvo
X-Vrk-Signature	Allekirjoitus pieninä heksadesimaaleina
X-Vrk-Timestamp	Aikaleima Unix-sekunteina (merkkijono)

Allekirjoituskaava: HMAC-SHA256(rawBody + timestamp, signing_secret) → pieninä heksadesimaaleina. Allekirjoitettu arvo on HTTP-pyynnön raaka runko-merkkijono, johon on liitetty aikaleima-merkkijono.

Node.js-esimerkki:

import crypto from 'node:crypto';

// raw = TÄSMÄLLEEN HTTP-pyynnön raakarunko-tavu/-merkkijono;
// älä serialisoi JSON:ia uudelleen
function verify(signingSecret, rawBody, headers) {
  const ts = headers['x-vrk-timestamp'];
  const sig = headers['x-vrk-signature'];
  // hylkää vanhentuneet toimitukset (uusintatoistohyökkäyssuoja)
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody + ts)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

:::caution Käytä raakaa runkoa. Älä koskaan jäsennä ja serialisoi JSON-runkoa uudelleen ennen allekirjoituksen laskemista — JSON:n uudelleenmuotoilu muuttaa tavut ja allekirjoitus ei täsmää. Lue HTTP-runko sellaisenaan ennen jäsennystä. :::

Valmis apufunktio (@varek/sdk)

Helpoin tapa on käyttää virallisen @varek/sdk -paketin constructWebhookEvent-funktiota, joka varmentaa allekirjoituksen (vakioaikainen vertailu), tarkistaa aikaleiman (oletusikkuna 300 s) ja jäsentää kirjekuoren yhdellä kutsulla:

import { constructWebhookEvent, VarekWebhookError } from '@varek/sdk';

const event = await constructWebhookEvent({
  secret: process.env.VAREK_WEBHOOK_SECRET,
  rawBody,                                  // raaka runko-merkkijono
  signature: headers['x-vrk-signature'],
  timestamp: headers['x-vrk-timestamp'],
});
// event = { id, type, created_at, data } — heitä 400, jos VarekWebhookError

Paketti vie myös WEBHOOK_EVENTS-tapahtumaluettelon ja tyypit. Koko tapahtumakatalogi on koneluettavana myös OpenAPI-määrittelyn webhooks-osiossa.

Uudelleenyritykset ja peruutus

VAREK yrittää toimittaa tapahtuman uudelleen, jos palvelimesi ei vastaa 2xx-tilakoodilla tai aika-ajo ylittyy. Uudelleenyrityksiä on enintään 6 eksponentiaalisella viiveellä (30 s, 60 s, 120 s … enintään n. 1 h).

Toimittamaton tapahtuma merkitään epäonnistuneeksi kaikkien yritysten jälkeen.

Toimitusloki ja Toista-toiminto

Kohdassa Asetukset → Webhookit → [päätepiste] → Toimitukset näet yksittäisen päätepisteen toimitushistorian: aikaleima, tapahtuman tyyppi, HTTP-statuskoodi ja mahdollinen virheviesti.

Voit toistaa minkä tahansa toimituksen Toista-painikkeella. Toisto lähettää saman alkuperäisen JSON-rungon uudelleen uudella X-Vrk-Timestamp- ja X-Vrk-Signature-arvolla — id pysyy samana.

Salaisuuden paljastaminen uudelleen

Jos whsec_…-salaisuus on kadonnut, hallituksen ylläpitäjä voi paljastaa sen kohdassa Asetukset → Webhookit → [päätepiste] → Näytä salaisuus. Salaisuus ei vaihdu automaattisesti — vain uuden päätepisteen luominen tai manuaalinen pyörittäminen luo uuden salaisuuden.

Katso myös

• Rajapinta (API) ja API-avaimet
• Asetukset ja tilaus
• Käyttäjät ja roolit