Maksu-webhook: varmista ilmoitus ja käsittele se kerran

Aloita tapahtuman liiketoiminnallisesta merkityksestä

Valitse ensin tapahtumat, joilla on vaikutusta tilauksen käsittelyyn. Maksun luominen, maksamisen aloittaminen ja vahvistettu suoritus eivät tarkoita samaa asiaa. Jos jokainen ilmoitus käynnistää toimituksen, tavara voi lähteä ennen kuin maksua on vahvistettu.

Kirjoita taulukko, jossa palvelun tapahtuma vastaa omaa sallittua tilamuutosta. Esimerkiksi vahvistettu maksu voi avata ostetun palvelun, kun taas keskeneräinen tila näyttää vain odotusviestin. Kaikki ilmoitukset eivät tarvitse asiakkaalle lähetettävää sähköpostia. Erottelu auttaa pitämään käsittelyn pienenä ja ennustettavana sekä vähentää tilanteita, joissa sama tekninen tapahtuma aiheuttaa useita toisistaan riippumattomia toimia.

Webhook-ilmoitukset

Tarkista allekirjoitus oikean ohjeen mukaan

Webhookin osoite ei ole salaisuus, johon voisi yksin luottaa. Vastaanottajan on tarkistettava allekirjoitus juuri lähettävän palvelun dokumentoimalla tavalla. Stripe-ilmoituksen esimerkkiä ei voi sellaisenaan käyttää OrsunPayn tapahtumaan, koska otsakkeet, salaisuudet ja viestin rakenne voivat erota.

Säilytä viestin runko tarkistusta varten ohjeen edellyttämässä muodossa. Jos väliohjelmisto muuttaa sisältöä ennen tarkistusta, oikeakin allekirjoitus voi näyttää väärältä. Epäonnistunut tarkistus ei saa muuttaa tilausta. Lokita tutkintaa varten turvallinen viite ja syy, mutta älä levitä koko maksutapahtuman sisältöä kaikkiin lokeihin. Salaisuuksien vaihdolle pitää olla erillinen dokumentoitu menettely.

Kehittäjätyökalut

Tallenna käsittely niin, että toisto on turvallinen

Sama ilmoitus voi tulla uudestaan, jos lähettäjä ei saanut odottamaansa vastausta. Tämä on tavallinen integraatiotilanne. Tapahtuman tunnisteen ja käsittelyn tuloksen tallentaminen auttaa havaitsemaan, onko työ jo tehty. Pelkkä sovelluksen muistissa oleva lista katoaa uudelleenkäynnistyksessä.

Huomioi myös samanaikaisuus: kaksi samaa ilmoitusta voi saapua lähes yhtä aikaa. Tilauksen päivitys ja käsittelymerkintä on toteutettava yhteensopivasti, jotta molemmat eivät käynnistä toimitusta. Jos erillinen jono lähettää viestejä tai aktivoi palvelun, myös sen toiminnon pitää sietää toisto. Ilmoituksen tunnistaminen ei yksin suojaa kaikkia myöhempiä sivuvaikutuksia.

Erota vastaanotto hitaasta jatkotyöstä

Laskun muodostaminen, usean järjestelmän päivittäminen tai ulkoisen viestin lähettäminen voi kestää. Vastaanottajan kannattaa tallentaa hyväksytty tapahtuma turvallisesti ja siirtää pidempi työ hallittuun käsittelyyn. Tarkka kuittauksen ajankohta määritetään käytetyn palvelun sopimuksen mukaisesti.

Onnistunut vastaus ei saa tarkoittaa vain sitä, että viesti kävi hetkeksi muistissa. Jos palvelin sammuu ennen pysyvää tallennusta, työ voi kadota. Toisaalta liian pitkä odotus voi aiheuttaa tarpeettomia uusia lähetyksiä. Määritä, mikä tapahtuma kuittauksessa luvataan: vastaanotto, tallennus vai lopullinen käsittely. Tee tästä ero myös valvontaan, jotta työntekijä ymmärtää mahdollisen viiveen.

Seuraa käsittelyn vaiheita

Asiakaspalvelun pitää löytää tilaus ja viimeinen vahvistettu maksutila. Kehittäjä tarvitsee lisäksi tiedon vastaanottoajasta, tarkistuksesta ja jatkotyön tuloksesta. Näin voidaan erottaa toisistaan saapumatta jäänyt ilmoitus ja ilmoitus, joka vastaanotettiin mutta jonka käsittely epäonnistui.

OrsunPay tarjoaa allekirjoitettuja webhookeja ja maksujen käsittelyn näkyvyyttä. Yrityksen oma tilausjärjestelmä tarvitsee silti omat tarkistuksensa. Ennen tapahtuman käsittelyä uudelleen varmista nykyinen maksutila ja jo suoritetut toimet. Palautuksen on oltava jäljitettävä: kuka käynnisti käsittelyn, mihin tapahtumaan se perustui ja mikä lopputulos syntyi. Käyttöoikeudet kannattaa rajata tehtävän mukaan.

Harjoittele viivettä ja väärää järjestystä

Kokeile tapahtuman saapumista ennen selaimen paluuta sekä sen jälkeen. Lähetä kontrolloitu sama ilmoitus uudelleen ja tarkista, että tilaus pysyy yhtenä tilauksena. Testaa myös virheellinen allekirjoitus, hetkellinen tietokantakatko ja palvelimen uudelleenkäynnistys käsittelyn aikana.

Älä käytä oikeiden asiakkaiden tietoja esimerkkiviesteissä. Kirjaa jokaiselle harjoitukselle odotettu tila ja todellinen havainto. Jos integraatio olettaa kaikkien viestien saapuvan täydellisessä järjestyksessä, muuta sitä ennen laajempaa käyttöä. Verkossa viiveet ovat mahdollisia, eikä maksun jälkeinen palvelu saa riippua siitä, kuinka nopeasti asiakkaan puhelin ja yrityksen palvelin sattuivat etenemään.

Anna ylläpidolle konkreettinen palautumisohje

Hyvä ohje alkaa kysymyksestä, onko maksu jo vahvistettu. Jos on, ongelma voi olla pelkästään tilauksen päivittämisessä. Uuden maksun luominen olisi silloin väärä ensimmäinen toimenpide. Ohjeen pitää kertoa, mistä alkuperäinen tapahtuma löytyy ja miten sen jo toteutuneet vaikutukset tarkistetaan.

Anna toisen työntekijän ratkaista kontrolloitu esimerkkitapaus ohjeen avulla. Jos ratkaisu vaatii käsin tehtyjä arvauksia tietokannasta, paranna työkalua tai dokumentaatiota. Tavoite on palauttaa keskeneräinen käsittely aiheuttamatta uutta maksua, toimitusta tai tarpeetonta asiakasviestiä. Tarkista sama menettely aina, kun tapahtumien rakenne, integraation versio tai sisäinen tilausprosessi muuttuu olennaisesti.

Lähteet

• Stripe Webhooks
• Stripe API: idempotent requests