Webhook-tilauksen avulla saat tiedon LivionKeyn tapahtumista omaan HTTPS-osoitteeseesi heti tapahtuman jälkeen, esimerkiksi kun avain noudetaan tai palautetaan. Tilauksia hallitaan API-näkymän Webhookit-välilehdellä. Tapahtumatietojen kuvaukset ja esimerkit allekirjoitusten tarkistamisesta löytyvät LivionKeyn webhook-kehittäjädokumentaatiosta (englanniksi).
Ennen kuin aloitat
Organisaatiollasi on oltava API-kommunikaatio käytössä. Jos et näe valikossa API-linkkiä, ota yhteyttä Livionin tukeen.
Tarvitset käyttäjäroolin, jolla voi hallita webhookeja, esimerkiksi Ylläpitäjä. Jos et näe Webhookit-välilehteä, pyydä apua organisaatiosi ylläpitäjältä.
Vastaanottavan järjestelmän ja sen osoitteen on täytettävä seuraavat vaatimukset:
Osoite käyttää HTTPS-protokollaa.
Järjestelmä on tavoitettavissa julkisesta internetistä. Yksityiset ja sisäverkon osoitteet hylätään.
Osoite ei sisällä käyttäjätunnusta, salasanaa eikä
#-merkillä alkavaa fragmenttiosaa.Järjestelmä vastaa suoraan. Uudelleenohjauksia ei seurata.
Tilauksen luonti
Valitse vasemmasta valikosta API ja avaa Webhookit-välilehti.
Valitse Luo uusi. Jos lista on tyhjä, valitse Luo webhook. Lisää webhook-tilaus -ikkuna avautuu.
Täytä alla kuvatut kentät ja valitse Tallenna.
Webhookin allekirjoitussalaisuus -ikkuna avautuu. Kopioi allekirjoitussalaisuus, tallenna se turvalliseen paikkaan ja valitse Sulje.
Kentät ovat:
Nimi — nimi, josta tunnistat tilauksen. Nimeä ei voi muuttaa myöhemmin.
Kohdeosoite (URL) — HTTPS-osoite, joka vastaanottaa tapahtumat.
Organisaatioyksikkö — yksikkö, jonka tapahtumista haluat ilmoituksia. Saat ilmoitukset myös sen aliyksiköiden tapahtumista. Yksikköä ei voi muuttaa myöhemmin.
Tapahtumat — yksi tai useampi tapahtumatyyppi:
Avaimen tila — avain noudetaan tai palautetaan, tai se merkitään noutamattomaksi tai palauttamattomaksi.
Sopimuksen päivitys — sopimus lisätään tai sitä muutetaan.
Koodi syötetty — laitteeseen syötetään oikea koodi (PIN-koodi, palautuskoodi tai kulkukoodi).
Laitehälytys — laitteen hälytys, kuten virta- tai yhteyshälytys, alkaa tai päättyy.
Uuden tilauksen tila on listassa Odottaa vahvistusta. Tapahtumia ei lähetetä, ennen kuin olet vahvistanut vastaanottavan osoitteen.
Allekirjoitussalaisuuden tallentaminen
Jokainen toimitus allekirjoitetaan tilauksen allekirjoitussalaisuudella. Salaisuus alkaa merkkijonolla whsec_. Vastaanottava järjestelmä varmistaa salaisuuden avulla, että toimitus on peräisin LivionKeystä.
TÄRKEÄÄ!
Salaisuus näytetään vain kerran, Webhookin allekirjoitussalaisuus -ikkunassa. Kun suljet ikkunan, salaisuudesta näkyvät vain neljä viimeistä merkkiä. Jos salaisuus katoaa, poista tilaus ja luo uusi. Olemassa olevan tilauksen salaisuutta ei voi vaihtaa.
Vastaanottavan osoitteen vahvistaminen
Avaa tilauksen tiedot valitsemalla tilaus listalta.
Valitse Lähetä testi.
LivionKey lähettää yhden allekirjoitetun testitoimituksen jokaisesta valitusta tapahtumatyypistä. Testitoimitukset sisältävät esimerkkiarvoja, eivät todellisia tapahtumatietoja. Kun vastaanottava järjestelmä vastaa jokaiseen testitoimitukseen 2xx-tilakoodilla, tilauksen tilaksi vaihtuu Aktiivinen ja tapahtumien lähetys alkaa. Jos testi epäonnistuu, korjaa vastaanottava järjestelmä ja valitse Lähetä testi uudelleen.
Jos tilaus on jo aktiivinen, Lähetä testi -toiminto tarkistaa vain yhteyden. Tila ei muutu.
Allekirjoitusten tarkistaminen
Tarkista jokaisen toimituksen allekirjoitus ennen kuin käsittelet sen. Toimitukset noudattavat Standard Webhooks -määritystä: jokaisessa pyynnössä on otsakkeet webhook-id, webhook-timestamp ja webhook-signature, ja allekirjoitus lasketaan allekirjoitussalaisuudellasi. Käytä Standard Webhooks -kirjastoa tai seuraa kehittäjädokumentaation ohjeita. Koodiesimerkit ovat saatavilla Node.js-ympäristöön sekä Python-, PHP- ja Go-kielille.
Toimitusten ja uudelleenyritysten seuraaminen
Listassa näkyvät jokaisen tilauksen Tila ja Viimeisin toimitustulos. Tilauksen tietojen kohdassa Viimeisin toimitus näkyvät viimeisimmän toimituksen tila, toimitusyritysten määrä, tapahtuma ja toimitustunniste. Valitse Näytä sisältö, niin näet lähetetyt tiedot. Vain viimeisin toimitus näytetään. Täydellistä toimitushistoriaa ei ole.
Vastaanottavan järjestelmän on vastattava 2xx-tilakoodilla 15 sekunnin kuluessa. Vastaa ensin ja käsittele tapahtuma vasta sen jälkeen. Muu tilakoodi, aikakatkaisu tai yhteysvirhe tulkitaan epäonnistumiseksi, ja LivionKey yrittää lähettää toimituksen uudelleen:
Toimitusta yritetään enintään 20 kertaa noin 6 tunnin aikana. Peräkkäisten yritysten odotusajat ovat 5 s, 15 s, 30 s, 1 min, 2 min, 5 min, 10 min, 15 min ja 20 min. Tämän jälkeen yritysten välillä odotetaan aina 30 minuuttia.
Kun toimitusta yritetään uudelleen, kohdassa Viimeisin toimitus näkyy Toimitus epäonnistuu – yritetään uudelleen sekä seuraavan yrityksen aika ja yritysten määrä tähän mennessä.
Jokaisessa uudelleenyrityksessä
webhook-id-otsakkeen arvo on sama. Sen avulla vastaanottava järjestelmä voi tunnistaa jo käsitellyn toimituksen.Jos vaihdat kohdeosoitteen uudelleenyritysten aikana, seuraava toimitusyritys tehdään uuteen osoitteeseen.
Tilauksen muokkaaminen, poistaminen käytöstä tai poistaminen
Avaa tilauksen tiedot ja valitse toiminto:
Muokkaa — muuta kohdeosoitetta kentässä Kohdeosoite (URL) tai tapahtumavalintoja kohdassa Tapahtumat. Nimeä ja organisaatioyksikköä ei voi muuttaa. Tapahtumavalintojen muutokset tulevat voimaan heti. Uusi kohdeosoite tallennetaan vain, jos jokaisen valitun tapahtumatyypin allekirjoitettu testitoimitus onnistuu uuteen osoitteeseen. Jos tarkistus epäonnistuu, mitään ei muuteta ja aiempi osoite pysyy käytössä.
Poista käytöstä — lopettaa toimitukset. Tilaksi tulee Poistettu käytöstä, ja käynnissä olevat uudelleenyritykset loppuvat. Tapahtumia, jotka syntyvät tilauksen ollessa pois käytöstä, ei lähetetä myöhemmin. Jatka toimituksia valitsemalla Aktivoi. Tilausta, joka ei ole koskaan läpäissyt testiä, ei voi aktivoida: käytä sen sijaan toimintoa Lähetä testi.
Poista — poistaa tilauksen pysyvästi. Käynnissä olevat uudelleenyritykset loppuvat.
Vanhat webhookit
Jos Livion on määrittänyt organisaatiollesi webhookeja ennen itsepalvelutilausten käyttöönottoa, niiden tila on listassa Vanha. Niitä ei voi muokata eikä testata.
Vanhan webhookin korvaaminen itsepalvelutilauksella:
Valitse vanhan webhookin rivi ja sitten Luo korvaava tilaus. Ikkuna on esitäytetty vanhan vastaanottimen tiedoilla.
Tallenna tilaus, tallenna allekirjoitussalaisuus ja vahvista vastaanottava osoite valitsemalla Lähetä testi.
Varmista, että vastaanottava järjestelmä käsittelee uudet toimitukset. Itsepalvelutilausten tapahtumatiedot lähetetään viestirakenteessa (envelope), joka eroaa vanhojen toimitusten muodosta. Katso kehittäjädokumentaatio.
Poista vanha vastaanotin. Tapahtumat toimitetaan sekä vanhan vastaanottimen että uuden tilauksen kautta, kunnes vanha vastaanotin on poistettu.
Tilausten hallinta API:n kautta
Voit hallita webhook-tilauksia myös LivionKey API v2:n kautta palvelutilillä. Luo tilaus kutsulla POST /webhookSubscriptions. Lue, muokkaa ja poista tilauksia käyttämällä HTTP-metodeja GET, PATCH ja DELETE. Lähetä testitoimitukset kutsulla POST /webhookSubscriptions/{id}/test. Katso API-dokumentaation Webhook Subscriptions -rajapinnat.
Palvelutilin luonti on kuvattu artikkelissa Palvelutilin luonti API-kommunikaatiota varten. API v2:n perusteet on kuvattu artikkelissa LivionKey API v2: Mechanical keys and key contracts (englanniksi).