Mikä on webhook? Ero API:in ja käyttö

01Mikä on webhook ja miten se toimii?

Webhook on yksinkertainen mekanismi, jonka avulla kaksi ohjelmistoa ilmoittaa toisilleen tapahtumista. Kun järjestelmässä tapahtuu jotain (esimerkiksi maksu vahvistetaan), se lähettää määrittämääsi URL-osoitteeseen HTTP-pyynnön, useimmiten POST-pyynnön. Pyynnön rungossa tapahtuman tiedot ovat yleensä JSON-muodossa.

Tätä rakennetta kutsutaan toisinaan myös käänteiseksi API:ksi tai tapahtumalaukaisimeksi. Viestinnän aloittaja on nimittäin dataa tuottava järjestelmä, ei sitä pyytävä. Sinä sanot vain kerran »kun tämä tapahtuu, ilmoita minulle tähän osoitteeseen»; loput hoituu automaattisesti.

Webhookin toiminnan ymmärtäminen on helpompaa, kun tiedät ensin vastauksen kysymykseen mikä on API. Webhook on osa API-maailmaa, mutta suunta kääntyy päinvastaiseksi.

1. Tapahtuma sattuu: uusi tilaus, palautuspyyntö, varasto loppuu, maksu vahvistetaan.
2. Lähdejärjestelmä lähettää POST-pyynnön rekisteröityyn webhook-osoitteeseen.
3. Vastaanottava järjestelmä vahvistaa pyynnön, käsittelee datan ja palauttaa 200:n kaltaisen vastauksen.
4. Jos vastausta ei tule, lähdejärjestelmä yrittää useimmiten pyyntöä uudelleen tietyin väliajoin.

02Webhookin ja API:n ero

Perinteisessä API-käytössä asiakas kysyy palvelimelta säännöllisin väliajoin »onko jotain uutta?». Tätä menetelmää kutsutaan pollingiksi (kyselyksi). Jos uutta dataa ei ole, jokainen pyyntö menee hukkaan; jos dataa on, on odotettava seuraavaan kyselyyn asti.

Webhookin ja API:n ero tulee esiin juuri tässä: webhookissa ei ole kysyjää vaan ilmoittaja. Ilmoitus tulee tapahtuman hetkellä, eikä turhaa liikennettä synny. Webhook ei kuitenkaan korvaa kaikkea; historiatietojen listaamiseen, suodattamiseen tai tietueiden päivittämiseen tarvitaan edelleen API.

03Webhookin käyttökohteet

Webhookin käyttö tulee vastaan lähes kaikessa digitaalisessa työssä. Maksupalvelut, toimitusyhtiöt, markkinapaikat, sähköpostipalvelut, koodivarastot ja viestintätyökalut antavat tapahtumailmoitukset useimmiten webhookilla.

Verkkokauppa ja maksut

Kun asiakas on suorittanut maksunsa, maksualusta lähettää kaupallesi »maksu onnistui» -ilmoituksen ja tilaus vahvistuu automaattisesti. Tämän ansiosta tilaus ei katoa uudelleenohjausta vaativissa maksuissa, kuten 3D Securessa, vaikka selain suljettaisiin. Tilausvirta on verkkokauppaintegraation ytimessä.

Toimitus ja markkinapaikka

Kun lähetys lähtee liikkeelle tai toimitetaan, toimitusjärjestelmä voi ilmoittaa tilan; asiakkaalle lähtee automaattinen tekstiviesti tai sähköposti. Samoin toimitusintegraatio- ja markkinapaikkaintegraatio-projekteissa uudet tilaukset, peruutukset ja palautukset käsitellään heti.

Ohjelmistokehitys ja tiimityökalut

Testien ja julkaisuprosessin käynnistäminen, kun koodivarastoon työnnetään uusi commit, ilmoituksen lähettäminen tiimin viestikanavalle, kun lomake täytetään, tai kalenterin päivittäminen varauksen saapuessa ovat tyypillisiä webhook-tilanteita.

04Esimerkki webhook-pyynnöstä

Webhook-pyyntö sisältää yleensä tapahtuman tyypin, ajan ja asianomaisen tietueen datan. Alla oleva esimerkki on tyypillinen runko, joka voitaisiin lähettää tilausta luotaessa. Kenttien nimet vaihtelevat palvelusta toiseen; noudata palvelun omaa dokumentaatiota.

Vastaanottopuolella riittää pieni päätepiste, joka ottaa pyynnön vastaan. Alla näet yksinkertaisen esimerkin, joka on kirjoitettu Node.js:llä ja Expressillä. Oikeassa projektissa mukaan on ehdottomasti lisättävä allekirjoituksen vahvistus ja jonorakenne.

{
  "event": "order.created",
  "created_at": "2026-01-15T10:24:00Z",
  "data": {
    "order_id": "10458",
    "total": 1249.90,
    "currency": "TRY",
    "status": "paid"
  }
}

const express = require('express');
const app = express();

app.post('/webhooks/siparis', express.json(), (req, res) => {
  const olay = req.body;
  // 1) Tarkista allekirjoitus  2) Lisää jonoon  3) Palauta vastaus heti
  console.log('Gelen olay:', olay.event);
  res.sendStatus(200);
});

app.listen(3000);

05Miten webhookin turvallisuus varmistetaan?

Webhook-osoite on internetiin avoin päätepiste. Jokainen, joka tuntee osoitteen, voi lähettää sinne väärennetyn pyynnön. Siksi mihinkään pyyntöön, jossa ei ole allekirjoituksen vahvistusta, ei pidä luottaa.

Useimmat vakavasti otettavat palvelut allekirjoittavat pyynnön jaetulla salaisella avaimella ja lähettävät allekirjoituksen HTTP-otsakkeessa. Vastaanottava järjestelmä tekee saman laskennan ja vertaa allekirjoituksia; täsmäämätön pyyntö hylätään.

• Käytä vain HTTPS-osoitetta; älä lähetä dataa tavallisella HTTP:llä.
• Ota ehdottomasti käyttöön HMAC-allekirjoituksen kaltainen vahvistusmenetelmä.
• Estä vanhojen pyyntöjen uudelleentoisto tarkistamalla pyynnön aikaleima.
• Älä kirjoita salaista avainta koodivarastoon; säilytä se ympäristömuuttujassa.
• Tarkista saapuvan datan skeema ennen sen kirjoittamista suoraan tietokantaan.

06Yleiset virheet ja ratkaisut

Webhookin pystyttäminen on helppoa, mutta sen toimintavarmuus vaatii huolellisuutta. Projekteissa yleisimmin vastaan tulevat ongelmat ovat uudelleen saapuvat pyynnöt ja hitaat vastaukset.

Saman tapahtuman käsittely kahdesti

Kun lähdejärjestelmä ei saa vastausta, se lähettää pyynnön uudelleen; siksi sama tilaus voi saapua kahdesti. Ratkaisu on idempotentti käsittely: tallenna jokaisen tapahtuman yksilöllinen tunniste ja jos jo käsitelty tunniste saapuu, palauta vain onnistumisvastaus ja jatka.

Aikakatkaisu

Jos päätepiste yrittää pyynnön saatuaan tehdä samalla pitkiä töitä, kuten laskun luontia tai sähköpostin lähetystä, vastaus viivästyy ja lähdejärjestelmä laskee sen virheeksi. Oikea tapa on ottaa pyyntö vastaan, lisätä se työjonoon ja vastata heti; raskaat työt etenevät taustalla.

Järjestyksen sekoittuminen

Tapahtumat eivät aina saavu siinä järjestyksessä kuin ne ovat syntyneet; »lähetetty»-ilmoitus voi saapua ennen »maksettu»-ilmoitusta. Tallenna tapahtuman aika tietueisiin ja arvioi tilasiirtymät sen mukaan.

07Webhook vai valmis automaatiotyökalu?

Yksinkertaisissa tilanteissa webhookeja kuuntelevat automaatiotyökalut toimivat ilman koodaamista. Näiden työkalujen vahvuudet ja heikkoudet kävimme läpi artikkelissamme mikä on low-code. Tilausten, maksujen ja varaston kaltaisissa liiketoiminnan ytimen virroissa on kuitenkin tärkeää, että hallinta on sinulla.

Jos liiketoimintasääntösi ovat erityiset, useita järjestelmiä yhdistetään toisiinsa tai datamäärä kasvaa, webhook-arkkitehtuurin rakentaminen omaan ohjelmistoon on luotettavampaa. Tässä räätälöity ohjelmistokehitys vähentää riippuvuutta välikerroksista.

Auroran ohjelmistoratkaisut ja integroidut ratkaisut perustuvat samaan periaatteeseen: järjestelmät keskustelevat suoraan keskenään ja turhat välikerrokset poistetaan.

08Tarkistuslista ennen webhookin käyttöönottoa

Vastaamalla seuraaviin kysymyksiin ennen automaattisen ilmoitusjärjestelmän pystyttämistä vältät suurimman osan myöhemmin ilmenevistä ongelmista.

1. Mitkä tapahtumat ovat todella tarpeen? Jokaisen tapahtuman tilaaminen aiheuttaa turhaa kuormaa.
2. Onko päätepiste tavoitettavissa HTTPS:n kautta ja tekeekö se allekirjoituksen vahvistuksen?
3. Pidetäänkö uudelleen saapuvista tapahtumista yksilöllistä tunnistetta?
4. Tallennetaanko epäonnistuneet pyynnöt ja voiko niitä seurata?
5. Onko olemassa varatarkistus, jolla data kerätään API:n kautta, jos webhook jää saapumatta?
6. Tarkistetaanko kriittisissä vaiheissa, kuten kirjanpidossa ja laskutuksessa, kaksoiskirjauksen riski kirjanpitointegraation avulla?