# Vastaanota tapahtumia webhookilla

URL: https://aihio.ai/ohjekeskus/tekoalyagentti/webhookit\
Kuvaus: Siirrä agentin tapahtumia omaan järjestelmääsi ja varmista saapuvien webhook-pyyntöjen aitous.

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](/ohjekeskus/tekoalyagentti/toiminnot).

## Ennen aloittamista

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ä.

> **Varoitus — Vastaanotin voi saada henkilötietoja:**
>
> Valitse vain tarvitsemasi tapahtumat ja rajoita niiden käsittely omassa
> järjestelmässäsi. Säilytä allekirjoitussalaisuus palvelimella. Älä kirjaa
> kokonaisia viesti- tai yhteystietosisältöjä tavallisiin sovelluslokeihin.

## Yhdistä vastaanotin

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.

## Valitse tapahtumat

| Tapahtuma                 | Käyttötarkoitus                                           |
| ------------------------- | --------------------------------------------------------- |
| `conversation.unanswered` | Käsittely tilanteelle, jossa kysymys jäi ilman vastausta. |
| `conversation.message`    | Keskusteluviestin käsittely omassa järjestelmässä.        |
| `lead.captured`           | Kerättyjen yhteystietojen jatkokäsittely.                 |

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ä.

## Varmenna allekirjoitus

Pyynnön mukana tulevat seuraavat otsakkeet:

| Otsake              | Sisältö                                                   |
| ------------------- | --------------------------------------------------------- |
| `X-Aihio-Event`     | Tapahtuman tyyppi.                                        |
| `X-Aihio-Delivery`  | Toimituksen tunniste kaksoiskappaleiden käsittelyyn.      |
| `X-Aihio-Signature` | Aikaleima ja allekirjoitus muodossa `t=AIKA,v1=TIIVISTE`. |

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.

## Kuittaus ja uudelleenyritykset

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.

## Jos tapahtumaa ei tule

- 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ä.
## Seuraavat vaiheet

- [Mukautetut HTTP-toiminnot](/ohjekeskus/tekoalyagentti/toiminnot) — Määrittele HTTPS-rajapintakutsu, jonka agentti täyttää ja palvelin suorittaa keskustelun aikana. Tunnukset säilytetään salattuina ja kutsut on suojattu.