Mikä on webhook? Miten sovellukset ilmoittavat toisilleen

Webhook on automaattinen viesti, jonka yksi palvelu lähettää sovelluksellesi heti, kun jotain tapahtuu. Kun asiakkaan maksu onnistuu, Stripe lähettää webhookin sovelluksesi osoitteeseen viestillä ”maksu onnistui, tässä tiedot”, ja sovelluksesi reagoi: merkitsee tilauksen maksetuksi, lähettää kuitin tai avaa tilin. Lyhyesti: API on sitä, että sovelluksesi kysyy toiselta palvelulta jotain; webhook on sitä, että toinen palvelu kutsuu sovellustasi ja kertoo jotain.

Miksi sillä on merkitystä, kun rakennat tekoälyllä

Heti kun sovelluksesi ottaa maksuja, vastaanottaa lomakkeita toisesta työkalusta tai yhdistyy palveluihin kuten GitHub, Shopify tai kalenteri, kohtaat webhookit. Ne ovat yleensä oikea tapa saada tietää, että jotain tapahtui — mutta juuri tässä tekoälyllä rakennetut sovellukset menevät usein hienovaraisesti pieleen:

• Päätepiste hyväksyy minkä tahansa pyynnön, joten kuka tahansa voi väärentää ”maksu onnistui” -tapahtuman.
• Sovellus antaa pääsyn kassan paluusivulla eikä webhookissa, joten ihmiset, jotka sulkevat välilehden liian aikaisin, eivät saa maksamaansa, ja ihmiset, jotka löytävät onnistumissivun URL-osoitteen, saavat sen ilmaiseksi.
• Sama tapahtuma tulee kahdesti, ja asiakas saa kaksi tilausta tai kaksi sähköpostia.

Webhookien toiminnan tunteminen auttaa pyytämään suojaukset jo etukäteen.

Arkinen vertauskuva: toimitusviesti

Voit selvittää, onko paketti saapunut, kahdella tavalla. Voit käydä ovella joka kymmenes minuutti tarkistamassa (se on pollaamista — sovelluksesi kysyy toistuvasti API:lta ”onko jotain uutta?”). Tai kuljetusliike voi lähettää sinulle tekstiviestin, kun paketti on toimitettu (se on webhook).

Viesti on selvästi parempi — kunhan voit luottaa siihen. Jos kuka tahansa voisi lähettää sinulle ”paketti toimitettu” -viestin, haluaisit varmistaa, että se tuli oikeasti kuljetusliikkeeltä. Ja jos puhelimesi oli kiinni, kun viesti tuli, haluaisit kuljetusliikkeen yrittävän uudelleen myöhemmin. Nämä kaksi asiaa — todentaminen ja uusintayritykset — ovat suurin osa webhookien hankaluudesta.

Miten webhook toimii, askel askeleelta

1. Luot päätepisteen sovelluksesi backendiin: URL-osoitteen, kuten https://yourapp.com/webhooks/stripe, joka hyväksyy POST-pyyntöjä.
2. Rekisteröit osoitteen palveluntarjoajalle ja valitset, mistä tapahtumista haluat tiedon (esimerkiksi ”kassa valmis” ja ”tilaus peruttu”).
3. Palveluntarjoaja antaa allekirjoitusavaimen. Tallennat sen palvelimellesi salaisuutena — katso ympäristömuuttujat ja salaisuudet.
4. Tapahtuma tapahtuu. Palveluntarjoaja lähettää HTTP-pyynnön osoitteeseesi JSON-sisällöllä, joka kuvaa tapahtuman, sekä allekirjoitusotsikon.
5. Sovelluksesi tarkistaa allekirjoituksen, tallentaa tapahtuman tunnisteen, vastaa nopeasti onnistumiskoodilla (200) ja tekee vasta sitten työn.
6. Jos sovelluksesi ei vastaa onnistumisesta, monet palveluntarjoajat yrittävät uudelleen myöhemmin.

Allekirjoitukset

Allekirjoitus todistaa, että pyyntö tuli palveluntarjoajalta eikä sitä ole muutettu. Stripe esimerkiksi laskee HMAC-tiivisteen (avainpohjaisen sormenjäljen) SHA-256-algoritmilla pyynnön rungosta ja aikaleimasta allekirjoitusavaimella, ja lähettää sen Stripe-Signature-otsikossa. Sovelluksesi tekee saman laskennan omalla kopiollaan avaimesta; jos tulokset täsmäävät, pyyntö on aito. Koska aikaleima on myös allekirjoitettu, voit hylätä vanhat pyynnöt, joita joku on tallentanut ja toistaa myöhemmin — Stripen kirjastojen oletussallittu viive on viisi minuuttia Stripen dokumentaation mukaan syyskuusta 2026.

Käytännön yksityiskohta: allekirjoitus lasketaan raakasta pyynnön rungosta. Jos kehyksesi jäsentää ja muotoilee JSON-datan uudelleen ennen tarkistusta, tarkistus epäonnistuu. Tämä on hyvin yleinen virhe.

Uusintayritykset, kaksoiskappaleet ja järjestys

Palveluntarjoajat eroavat toisistaan, joten tarkista kunkin dokumentaatio. Syyskuun 2026 tilanne:

Stripen dokumentaatio kertoo myös, ettei tapahtumien saapumisjärjestystä ole taattu ja sama tapahtuma voi harvoin tulla useammin kuin kerran, joten se suosittelee tapahtumatunnisteiden seuraamista.

Yleinen opetus pätee kaikkiin palveluntarjoajiin: tapahtumat voivat saapua myöhässä, useammin kuin kerran ja väärässä järjestyksessä. Käsittelijäsi pitäisi olla idempotentti — saman tapahtuman käsittely kahdesti antaa saman tuloksen kuin käsittely kerran.

Esimerkki: maksullisen kurssin avaaminen

Myyt verkkokurssia. Opiskelija napsauttaa Osta, maksaa Stripen isännöimällä kassasivulla ja palaa sivustollesi.

Hauras tapa: kiitossivu avaa kurssin. Jos opiskelija sulkee selaimen uudelleenohjauksen aikana, hän on maksanut mutta ei saa pääsyä. Jos joku arvaa kiitossivun URL-osoitteen, hän saa pääsyn ilmaiseksi.

Webhook-tapa:

1. Kun Stripe vahvistaa maksun, se lähettää tapahtuman checkout.session.completed osoitteeseen /webhooks/stripe.
2. Backendisi tarkistaa allekirjoituksen allekirjoitusavaimella. Jos se epäonnistuu, se vastaa 400 eikä tee mitään.
3. Se tarkistaa, onko tapahtuman tunniste jo käsitelty. Jos on, se vastaa 200 ja lopettaa.
4. Se tallentaa tapahtuman tunnisteen, vastaa 200 ja antaa sitten opiskelijalle pääsyn sekä lähettää tervetuloviestin.
5. Kiitossivu vain kertoo ”Maksu vastaanotettu — kurssisi ilmestyy hetken kuluttua” ja tarkistaa opiskelijan pääsytilan.

Myöhemmin, jos tilaus perutaan tai kortti hylätään, muut webhook-tapahtumat kertovat sovelluksellesi, että pääsy pitää poistaa tai keskeyttää. Näin tilausmallin tuotteet pysyvät synkronissa laskutuksen kanssa — katso mikä SaaS on ja kuinka maksut lisätään sovellukseesi.

Keskeiset termit

• Päätepiste (endpoint): sovelluksesi URL-osoite, joka vastaanottaa webhookit.
• Tapahtuma / hyötykuorma (payload): mitä tapahtui ja sen kuvaava data (yleensä JSON).
• Allekirjoitusavain: jaettu salaisuus, jolla allekirjoitukset tarkistetaan.
• Idempotentti: turvallinen ajaa useammin kuin kerran samalla tuloksella.
• Pollaaminen: toistuva kysely API:lta muutosten varalta sen sijaan, että odotettaisiin webhookia.
• Tunneli: työkalu, joka antaa kannettavalle väliaikaisen julkisen URL-osoitteen, jotta webhookit voivat saavuttaa sen kehityksen aikana.

Yleisiä virheitä ja väärinkäsityksiä

• Allekirjoitusten tarkistamatta jättäminen. Päätepisteen URL ei ole salaisuus. Tarkistus on se, mikä tekee pyynnöstä luotettavan.
• Hidas työ ennen vastausta. Sähköpostien lähetys tai PDF-tiedostojen luonti ennen vastaamista voi aiheuttaa aikakatkaisuja, jotka laukaisevat uusintayrityksiä, jotka aiheuttavat kaksoiskappaleita.
• Oletus, että tapahtuma tulee kerran ja järjestyksessä. Tallenna tapahtumatunnisteet äläkä luota saapumisjärjestykseen.
• Esikatseluosoitteen käyttö. Webhookit tarvitsevat vakaan, julkisen osoitteen. Yksityiset esikatselut ja localhost eivät ole tavoitettavissa internetistä; käytä julkaistua osoitetta (tai tunnelia testatessa).
• Testi- ja live-salaisuuksien sekoittaminen. Palveluntarjoajat antavat usein eri allekirjoitusavaimet testi- ja live-tilalle. Tallenna molemmat ja käytä oikeaa.
• Päätösten tekeminen pelkän hyötykuorman varassa. Tärkeissä päätöksissä on järkevää hakea uusin tila palveluntarjoajan API:sta webhookin saapumisen jälkeen.

Mitä pyytää tekoälyrakentajalta

Lisää palvelimelle POST /webhooks/stripe-päätepiste. Tarkista Stripen allekirjoitus raakan pyynnön rungon ja salaisuuden STRIPE_WEBHOOK_SECRET avulla. Hylkää virheelliset allekirjoitukset koodilla 400. Tallenna jokaisen tapahtuman tunniste ja ohita jo käsitellyt tapahtumat. Vastaa nopeasti koodilla 200 ja käsittele sitten checkout.session.completed merkitsemällä tilaus maksetuksi ja lähettämällä kuitti. Kirjaa tapahtuman tyyppi. Älä anna pääsyä kassan onnistumissivulta.

Testaa sen jälkeen: lähetä testitapahtuma palveluntarjoajan dashboardista, lähetä sama uudelleen ja lähetä pyyntö väärällä allekirjoituksella. Vain ensimmäisen pitäisi muuttaa jotain.

Webhookit Mythexissä

Mythex ei pyöritä erillistä webhook-palvelua. Pyydät agenttia lisäämään webhook-päätepisteen sovelluksesi omaan backendiin ja osoittamaan palveluntarjoajan julkaistuun URL-osoitteeseen, koska webhookit tarvitsevat julkisen osoitteen. Allekirjoitussalaisuus menee projektisi salaisuuksiin, ja jos muutat sitä live-sovelluksessa, julkaise uudelleen. Webhookien käsittely -reseptissä on aloitusohje, ja kauppapohjat ovat hyvä lähtökohta sovelluksille, jotka ottavat maksuja.

Kysymykset