Proaktiivinen Tampuuri API

Tampuuri API on tarkoitettu toimimaan moottorina prosessien automatisoinnissa sekä tietojen synkronoinnissa ja välittämisessä kahden sovelluksen välillä. Tampuuri APIsta on kuitenkin puuttunut yksi ominaisuus, nimittäin proaktiivinen tapa ilmoittaa tapahtumista.

Webhookit tarjoavat tavan lähettää ilmoituksia kolmannen osapuolen sovellukselle aina, kun joku tietty toimenpide tapahtuu Tampuurissa. Yksinkertaisesti sanottuna API toimii passiivisesti, kun kysyt siltä, saat vastuksen. Webhook taas toimii proaktiivisesti, kun tietyt kriteerit täyttyvät, saat siitä automaattisesti hälytyksen.

Kun Tampuuri API:a ja Webhookeja käytetään yhdessä, voidaan luoda järjestelmä, joka pystyy toimittamaan oikeat tiedot oikeaan aikaan.

Webhook lyhyesti

Webhook on erilainen lähestymistapa kuin tyypillinen REST API. Toisin kuin tavallinen REST API, webhook kääntää keskustelun suunnan. Asiakkaalla itsellään on kuuntelija (sovellus), johon Tampuuri työntää (push) tietoja sellaisenaan. Tätä päätepistettä kutsutaan webhookiksi.

Asiakkaan ei tarvitse tehdä toistuvia pyyntöjä API:in (pollausta) vaan Tampuurista ilmoitetaan kuuntelijalle tapahtumasta proaktiivisesti. Tämä API:n proaktiivinen malli sopii hyvin tilanteisiin, joissa taustalla olevat tiedot päivittyvät jatkuvasti, kuten vikailmoitukset tai dokumenttipankin tiedot. Webhook on myös omiaan tilanteeseen, jossa taustalla olevan tiedon massat ovat yksinkertaisesti liian suuria pollattavaksi nopealla syklillä.

Webhooks ja Tampuuri API

Tampuuri API ja Webhookit yleisellä tasolla.

Webhookit eivät poista tarvetta Tampuuri API:n käyttämiseen, eikä Webhookkeja voi käyttää ilman Tampuuri API:a. Webhook on käytännössä heräte ja itse tapahtuman täydelliset tiedot haetaan Tampuuri API:n välityksellä. Kuten jo aikaisemmin mainittiin, Webhookeilla pyritään vähentämään API:n “turhaa” kutsumista.

Vähän kuin joka minuutin välein käytäisiin postilaatikolla vain toteamassa postilaatikon olevan tyhjä. Mieluummin käydään katsomassa postilaatikkoa vain silloin, kun siellä on jotain katsottavaa.

Herätteen sisältö

Webhook herätteen sisällä ei koskaan lähetetä kaikkea tapahtumaan liittyvää tietoa vaan herätteessä tulee vain ne kriittisimmät ja tärkeimmät tiedot liittyen tapahtumaan. Alla olevassa esimerkissä on yksittäisen ilmoituksen tila muuttunut Vastaanotettu-tilaan eli ilmoitus on käytännössä otettu työn alle ja esimerkissä on kaikki tieto mitä ilmoituksesta herätteen mukana tulee:

{
”Id”: ”5ae4d711b67544e0916c215805ef1e84”,
”Attempt”: 1,
”Properties”: {},
”Notifications”: [
{
”Action”: ”IlmoitusTilamuutos”,
”Id”: ”8c0903dc-0dad-4dcf-87a7-6369c7e0ba2a”,
”Account”: ”Asiakkaan tilin nimi”,
”ReferenceId”: ”1514959”,
”ReferenceSecondaryId”: ”770230f3-66a2-4a38-a242-66356393af4d”,
”ReferenceData”: ”Vastaanotettu”,
”ReferenceJson”: null,
”Timestamp”: ”2019-01-29T09:12:10.24Z”,
”DateTimeZone”: ”UTC”
}
]
}

Vaikka herätteen mukana tuleekin suhteellisen paljon tietoa, Account ja ReferenceId tietojen perusteella voidaan hakea itse ilmoitukseen liittyvät tiedot Tampuuri API:sta. Esimerkiksi ilmoitukset täydelliset tiedot, jos niitä tarvitaan, voidaan hakea API:sta seuraavalla kutsulla:

Vikailmoituksen (huoltopyynnön/palvelupyynnön) ilmoituksen tietojen hakeminen

GET ilmoitukset/{id} “Palauttaa ilmoituksen täydet tiedot.”

Tapahtumatyypit

Tampuurista lähtee tällä hetkellä Webhook herätteitä vain kahdesta erillisestä tapahtumasta. Toinen liittyy ilmoituksen tilan muuttamiseen ja toinen asuntotarkastuksen tilan muuttamiseen. Tapahtumatyyppejä lisätään Tampuurin kehittämisen yhteydessä lisää ja seuraavaksi on tulossa esimerkiksi uuden ilmoituksen lisäämisestä oma Webhook tapahtumatyyppi “IlmoitusUusi”.

  • IlmoitusTilamuutos
  • AsuntotarkastusTilamuutos
  • AsuntotarkastusUusi
  • DokumenttipankkiDokumenttiUusi
  • DokumenttipankkiDokumenttiMuokkaa
  • DokumenttipankkiDokumenttiPoista
  • KohderekisteriTietoMuokkaa
  • IlmoitusUusi tulossa

Webhookkien ylläpito Tampuurin ylläpidossa

Jotta asiakkaan itse kehittämälle kuuntelijalle voidaan lähettää herätteitä, pitää Webhookin julkinen osoite käydä rekisteröimässä Tampuuri Ylläpito/Webhooks kohdassa. Tampuurin päässä annetaan kuuntelijan osoite sekä mitä Tapahtumatyyppejä kuuntelija haluaa saada vastaanotettua. Kuuntelijoita voidaan lisätä useita, jos eri kuuntelijat hoitavat eri Tapahtumatyyppeihin liittyviä jatkotoimenpiteitä.

Tampuurin käyttöliittymä Webhookkien rekisteröimiseen.

Käytännön käyttötapaukset

Vaikka Webhooks on karkea mekanismi notifikaatioiden lähettämiseen, ne ovat myös yksinkertaisia ja tehokkaita. Webhookkien avulla voidaan rakentaa myös hyvin monimutkaisia jatkotoimenpiteitä Tampuurin tapahtuman jälkeen.

Yhtenä hyvänä käytännön esimerkkinä voisi mainita vikailmoituksen valmiiksi kuittaamisen. Kun vikailmoitus kuitataan Tampuurissa valmiiksi, voidaan tämän jälkeen välittömästi lähettää asiakastyytyväisyyskysely ja saada välitöntä palautetta asiakkaan itse jättämästä vikailmoituksesta.

Tämä on vain yksi käytännön esimerkki, mutta erittäin hyvä, kuvaamaan sitä miten Webhookkien avulla voidaan saada selville asiakastyytyväisyyden tasoa sekä tämän jälkeen tehdä toimenpiteitä asiakastyytyväisyyden parantamiseen.

Yksinkertaistettu prosessi asiakastyytyväisyyskyselyiden automatisoituun lähettämiseen Tampuurin Webhookkien avulla.

Kiinnostuitko? Haluaisitko tietää enemmän Tampuuri API:sta ja webhookista?

Jätä yhteydenottopyyntö niin keskustellaan yhdessä, kuinka voit hyödyntää Tampuuria mahdollisimman tehokkaasti.