Vastaanota tapahtumia webhookilla

Webhook lähettää tapahtuman Aihiosta omaan HTTPS-osoitteeseesi. Voit esimerkiksi viedä yhteystietopyynnön omaan järjestelmääsi tai käynnistää käsittelyn kysymykselle, johon agentti ei osannut vastata.

Webhook ilmoittaa tapahtumasta. Jos agentin pitää hakea tietoa tai tehdä toiminto kesken keskustelun, käytä sen sijaan HTTP-toimintoa .

Tarvitset webhookeja tukevan tilauksen, oikeuden hallita integraatiota sekä julkisesta verkosta saavutettavan HTTPS-vastaanottimen. Vastaanottimen pitää tarkistaa allekirjoitus, käsitellä kaksoiskappaleet ja hyväksyä tapahtuma nopeasti. Yksityisiin verkko-osoitteisiin ei voi lähettää pyyntöjä.

1. Valmistele HTTPS-osoite

   Luo palvelimellesi POST-pyyntöjä vastaanottava osoite. Säilytä pyynnön alkuperäinen runko allekirjoituksen tarkistusta varten ennen JSON-jäsentämistä.

2. Lisää webhook Aihioon

   Avaa Oma Aihio -palvelun integraatioasetukset. Lisää agentille webhook, anna vastaanottimen HTTPS-osoite ja valitse tarvitsemasi tapahtumat. Tallenna saamasi allekirjoitussalaisuus vastaanottimen suojattuun asetukseen.

3. Tarkista yksi tapahtuma päästä päähän

   Tuota valitsemaasi tapahtumaa vastaava tilanne testitiedoilla. Varmista vastaanottimelta oikea tapahtumatyyppi, hyväksytty allekirjoitus ja onnistunut käsittely. Tarkista myös toimituksen tila Aihiossa.

JSON-rungon yhteiset kentät ovat event, created_at ja data. data sisältää tapahtumakohtaisen sisällön. Valitse käsittely event-arvon mukaan äläkä oleta kaikkien tapahtumien sisältävän samoja kenttiä.

Pyynnön mukana tulevat seuraavat otsakkeet:

Allekirjoitus on HMAC-SHA256-tiiviste merkkijonosta aikaleima.alkuperäinenRunko. Aikaleima on Unix-aika sekunteina, ja tiiviste on pienaakkosin kirjoitettu heksadesimaalimerkkijono.

1. Lue t ja v1 allekirjoitusotsakkeesta. Hylkää puuttuvat tai virheelliset arvot.
2. Tarkista, että aikaleima on vastaanottimellesi hyväksyttävän lyhyen aikaikkunan sisällä. Pidä palvelimen kello ajan tasalla.
3. Laske odotettu tiiviste tallennetulla salaisuudella ja täsmälleen saapuneella rungolla. JSON:n uudelleenmuotoilu muuttaa allekirjoitettua sisältöä.
4. Vertaa tiivisteitä vakioaikaisella vertailulla ennen tapahtuman käyttämistä.
5. Käsittele sama X-Aihio-Delivery vain kerran, vaikka pyyntö saapuisi uudelleen.

Pelkkä otsakkeen olemassaolo ei riitä aitouden todisteeksi. Testaa myös väärä allekirjoitus: vastaanottimen pitää hylätä pyyntö ilman sivuvaikutuksia.

Palauta onnistunut HTTP-tila vasta, kun olet ottanut tapahtuman turvallisesti käsittelyyn. Siirrä pitkä työ omaan luotettavaan jonoosi; lähettäjän aikakatkaisu on 10 sekuntia. Älä palauta onnistumista, jos vastaanotto epäonnistui.

Aihio yrittää epäonnistunutta toimitusta uudelleen rajatusti. Nykyinen enimmäismäärä on kolme yritystä. Toimitus ei ole täsmälleen kerran tapahtuva käsittely eikä uudelleenyritysten kellonaika ole takuu. Suunnittele vastaanotin siten, ettei toistuva pyyntö luo esimerkiksi samaa yhteystietoa kahdesti.

• Tarkista, että webhook on käytössä ja tilannut juuri kyseisen tapahtuman.
• Tarkista osoitteen saavutettavuus, TLS-varmenne ja vastaanottimen lokien tilakoodi ilman henkilötietoja.
• Jos allekirjoitus ei täsmää, tarkista salaisuus, alkuperäinen pyyntörunko ja palvelimen kello.
• Jos käsittely kestää liian kauan, siirrä työ jonoon ja kuittaa turvallinen vastaanotto nopeasti.

Poista webhook käytöstä ennen vastaanottimen poistamista tai osoitteen sulkemista. Säilytä toimitustunniste ja virheen ajankohta mahdollista tukiselvitystä varten, älä lähetä salaisuutta tukipyynnössä.