Webhookit #

Webhookien avulla Your AI Connector voi ilmoittaa automaattisesti muille liiketoimintatyökaluillesi aina, kun jotain tärkeää tapahtuu – uusi yhteystieto luodaan, tapaaminen varataan tai viesti vastaanotetaan. Sen sijaan, että tarkistaisit päivitykset manuaalisesti, yhdistetyt järjestelmäsi saavat välittömän ilmoituksen heti, kun jotain tapahtuu.

Mitä webhookit ovat? #

Ajattele webhookia kuin automaattista tekstiviestiä kahden sovelluksen välillä. Kun Your AI Connector-palvelussa tapahtuu jotain (kuten uuden yhteystiedon rekisteröityminen), alusta lähettää välittömästi ilmoituksen valitsemaasi toiseen järjestelmään. Annat verkko-osoitteen (niin kutsuttu “webhook URL”), johon nämä ilmoitukset lähetetään – tämän osoitteen tarjoaa yleensä CRM-järjestelmäsi, automaatioalustasi tai kehittäjäsi.

Webhookit lähettävät tietoa vain Your AI Connector-palvelusta POIS. Webhook on yksisuuntainen katu Your AI Connector-palvelusta muihin työkaluihisi. Ei ole olemassa webhook-URL-osoitetta, joka lähettäisi liidejä, yhteystietoja tai viestejä alustalle. Jos haluat tuoda uuden liidin sisään – verkkosivuston lomakkeelta, CRM-järjestelmästäsi tai GoHighLevelistä – järjestelmäsi tekee sen sijaan API-kutsun. Katso API-käyttöoikeus (toiminto Luo yhteystieto) ja Suppilot. Ainoa asia, jota tarvitset sisääntulevaa liikennettä varten, on API-avaimesi, joka löytyy omasta osiostaan – katso API-käyttöoikeus. Tässä kuvattu Webhookit-sivu on tarkoitettu yksinomaan ulospäin suuntautuvalle liikenteelle.

Yleisiä käyttötapoja ovat:

• Uusien yhteystietojen synkronointi CRM-järjestelmään.
• Työnkulun käynnistäminen Zapierissa, Makessa tai Pabblyssa, kun tunniste lisätään.
• Tiimin ilmoittaminen Slackissa, kun ihmisen apua tarvitaan.
• Kalenterijärjestelmän päivittäminen, kun aika varataan.
• Keskusteluyhteenvetojen tallentaminen tietokantaasi.

Webhookien määrittäminen #

1. Napsauta vasemmasta sivupalkista Asetukset (rataskuvake).
2. Napsauta Asetukset-sivupalkin Integraatiot-ryhmän alta Webhookit.

Tilillä, jolle ei ole vielä määritetty webhookeja, sivu näyttää tältä:

3. Napsauta New webhook oikeasta yläkulmasta. Lomake avautuu sivulle:

4. Täytä:
   • Päätepisteen URL (Endpoint URL) — verkko-osoite, johon Your AI Connector lähettää tapahtumailmoitukset. Saat tämän ulkoisesta järjestelmästäsi (CRM, automaatioalusta tai oma palvelin).
   • Nimi — tunniste, jonka tunnistat myöhemmin (esim. “Slack-hälytykset” tai “CRM-synkronointi”). Vain omaa viitettäsi varten.

Webhook URL-osoitteesi on oltava julkisesti tavoitettavissa oleva https://-osoite. Tavalliset http://-osoitteet, localhost- tai yksityisverkon osoitteet sekä alustan sisäiset osoitteet hylätään tallennettaessa. Jos haluat testata omalta koneeltasi, käytä julkista tunnelia (webhook.site tai ngrok) localhostin sijaan.

5. Valitse Tapahtumat-kohdassa ne tapahtumat, jotka haluat tämän webhookin vastaanottavan – kaikki 22 on lueteltu kohdassa 22 webhook-tapahtumaa.
6. (Valinnainen) Ota käyttöön Yritä epäonnistuneita toimituksia uudelleen, jos haluat Your AI Connector-palvelun yrittävän uudelleen väliaikaisen virheen sattuessa – katso Epäonnistuneiden toimitusten uudelleenyrittäminen.
7. Napsauta Luo webhook. Se ilmestyy lomakkeen alapuolella olevaan luetteloon, ja voit napsauttaa sen rivillä olevaa Testaa-painiketta milloin tahansa lähettääksesi näytehyötykuorman päätepisteeseesi.

Käyttöoikeus vaaditaan. Webhookien lisääminen, muokkaaminen tai testaaminen vaatii Integraatioiden “muokkaus”-oikeuden (vain katseluoikeudella varustetut tiimin jäsenet näkevät lomakkeen sijasta vain luku -ilmoituksen).

Webhookin allekirjoittaminen vaatii, että se on jo tallennettu – avaa olemassa olevan webhookin rivi muokataksesi sitä, jolloin Allekirjoituksen salaisuus -paneeli ilmestyy muokkauslomakkeen alaosaan. Upouudella, tallentamattomalla luonnoksella ei ole vielä allekirjoitusvaihtoehtoa – katso Allekirjoitetut hyötykuormat alta.

Yksi webhook kaikille asiakastileillesi (toimistot) #

Jos hallinnoit toimistoa, sinun ei tarvitse luoda samaa webhookia uudelleen jokaiselle asiakastilille. Toimistotilin webhook-lomakkeessa on ylimääräinen kytkin: Käynnistä myös kaikille asiakastileille. Kun otat sen käyttöön, tämä webhook vastaanottaa myös tapahtumia, jotka tapahtuvat kaikilla toimistosi alaisilla asiakastileillä – yksi päätepiste, koko toimisto.

Miten se toimii:

• user-lohko kertoo, mille asiakkaalle tapahtuma kuuluu. Jokainen ilmoitus sisältää jo user-lohkon, joka yksilöi tilin, jolla tapahtuma sattui, joten automaatiosi voi reitittää tiedot asiakaskohtaisesti.
• Webhookisi omat asetukset pätevät kaikkialla. Valitsemiasi tapahtumia, allekirjoitussalaisuutta ja uudelleenyritysasetusta käytetään myös asiakastilien toimituksissa.
• Ei kaksoistoimituksia. Jos asiakastilillä on oma webhook, joka osoittaa samaan URL-osoitteeseen, sitä käytetään kyseisen tilin tapahtumiin – sama tapahtuma ei koskaan saavu kahdesti samaan päätepisteeseen.
• Asiakkaat eivät näe sitä. Webhook ei näy asiakastilin omalla Webhooks-sivulla, eivätkä asiakkaat voi kytkeä sitä pois päältä – se on sinun hallittavissasi.
• Luotettavuutta seurataan asiakastilikohtaisesti. Jos päätepisteesi epäonnistuu toistuvasti, se kytketään automaattisesti pois päältä vain siltä tililtä, jonka toimitukset epäonnistuivat (katso Webhookin luotettavuus), ei koko toimistolta kerralla.

Kytkin näkyy vain toimistotileillä. Sen asettaminen API:n kautta on myös tuettu – katso apply_to_sub_accounts-kenttä kohdasta Webhooks API.

Käytettävissä olevat käynnistystapahtumat #

Voit ottaa kunkin 22 webhook-tapahtumasta käyttöön tai poistaa ne käytöstä itsenäisesti. Kun tapahtuma laukeaa, Your AI Connector lähettää ilmoituksen webhook-URL-osoitteeseesi asiaankuuluvien tietojen kera. Jokainen tapahtuma, sen merkitys ja event-koodi, jonka se lisää hyötykuormaan, on lueteltu yhdessä kohdassa 22 webhook-tapahtumaa alempana tällä sivulla.

Hyvä tietää: Tehtävä luotu, Tehtävä päivitetty ja Tehtävä suoritettu ovat täysin valittavissa ja tallentuvat oikein. Päivittäinen yhteenveto luotu on myös hiljattain lisätty. Katso kyseisen hyötykuorman muoto kohdasta Tehtävä suoritettu -webhook.

Tunnisteisiin perustuvat webhook-käynnistimet #

subscribed_to_tags ei rajaa webhookin tapahtumia tunnisteeseen. Se vain kaventaa sitä, mitkä tunnisteet tuottavat keskusteluyhteenvedon ilmoituksen. Jos haluat pyynnön tietyn tunnisteen lisäämisestä, määritä webhook-URL kyseiselle tunnisteelle agentin (tai kampanjan) Tunnisteet-välilehdellä.

Itse webhook-lomakkeessa ei ole tunnisteiden valintatyökalua, ei uutta webhookia luotaessa eikä olemassa olevaa muokattaessa, joten subscribed_to_tags voidaan lukea tai muuttaa vain Webhooks API:n kautta tai pyytämällä tukea.

Hyvä tietää: olemassa olevan webhookin muokkaaminen, jolla on subscribed_to_tags-luettelo (uudelleennimeäminen, tapahtumien muuttaminen, uudelleenyritysten vaihtaminen), ei enää tyhjennä kyseistä luetteloa — koska lomakkeessa ei ole tunnisteiden valintatyökalua, jota lähettää takaisin, tältä sivulta tallentaminen jättää nykyisen luettelon ennalleen. (Tämä oli todellinen virhe ennen 21. heinäkuuta 2026: webhook-lomakkeesta tallentaminen pyyhki aiemmin luettelon, koska se lähetti aina tyhjän tunnisteiden luettelon. Jos webhook menetti subscribed_to_tags-luettelonsa ennen kyseistä päivämäärää, se on määritettävä uudelleen API:n kautta.)

Luo yhteenveto tunnisteella merkityille yhteyshenkilöille #

Jos webhookilla on subscribed_to_tags-luettelo, voit ottaa käyttöön Luo yhteenveto. Kun tämä on käytössä, Your AI Connector luo automaattisesti keskusteluyhteenvedon yhteyshenkilölle, kun jokin näistä tunnisteista lisätään, ja sisällyttää sen webhook-tietoihin — täysi konteksti ilman erillistä pyyntöä.

Webhookin testaaminen #

1. Avaa Asetukset → Integraatiot → Webhookit.
2. Napsauta webhookisi rivillä Testaa.
3. Tarkista ulkoisesta järjestelmästäsi, että se vastaanotti testitiedot.
4. Tarkista tietomuoto varmistaaksesi, että järjestelmäsi osaa jäsentää sen oikein.

Tee täydellinen päästä-päähän-testi lähettämällä viesti, joka käynnistäisi jonkin määritetyistä tapahtumistasi (lähetys tai saapuva viesti yhdistetyssä kanavassa), ja varmista, että webhook laukeaa todellisilla tiedoilla.

Mikä lasketaan onnistuneeksi toimitukseksi #

Riippumatta siitä, napsautatko Test-painiketta vai tapahtuuko tapahtuma oikeasti, lähetämme saman asian:

• POST-pyyntö (ei koskaan GET), jonka runko on JSON-muodossa ja Content-Type: application/json.
• Otsikot, jotka on lueteltu kohdassa Allekirjoitetut hyötykuormat. Allekirjoitusotsikot sisällytetään vain, kun olet määrittänyt allekirjoitussalaisuuden.

Pidämme toimitusta onnistuneena, kun:

• Päätepisteesi vastaa millä tahansa 2xx-tilakoodilla (200, 201, 204 — kaikki käyvät).
• Se vastaa 30 sekunnin kuluessa.

Muutama asia, joka yllättää ihmiset:

• Vastausrunkoa ei huomioida. Sinun ei tarvitse palauttaa mitään tiettyä JSON-muotoa. Tyhjä 200-vastaus riittää.
• Uudelleenohjaukset lasketaan epäonnistumiseksi. Emme seuraa niitä, joten 301- tai 302-vastaus (mukaan lukien uudelleenohjaus vinoviivan puuttumisen vuoksi tai http-ohjaus https-osoitteeseen) kirjataan epäonnistuneeksi toimitukseksi. Tallenna lopullinen URL-osoite, älä sitä, joka ohjaa uudelleen.
• Kyselymerkkijonoja tuetaan täysin. https://your-app.com/hook?token=abc123 lähetetään täsmälleen sellaisena kuin tallensit sen, joten tunnisteen lisääminen kyselymerkkijonoon toimii yhtä hyvin kuin sen lisääminen polkuun.
• URL-osoitteesi on oltava https:// ja julkisesti tavoitettavissa. Osoitteet, jotka kuuluvat Your AI Connector:n omaan infrastruktuuriin, hylätään, mutta omat päätepisteesi Google Cloud Functionsissa, Cloud Runissa, App Enginessä, Firebase Hostingissa tai missä tahansa muualla toimivat hyvin.
• Päätepisteesi edessä oleva palomuuri tai bottisuojauskerros voi estää meitä. Yleisin tapaus on Cloudflare: jos vyöhykkeelläsi on päällä Bot Fight Mode tai hallittu haaste, pyyntömme saa “Just a moment…” -haastesivun ja 403-virheen sen sijaan, että se tavoittaisi palvelimesi – ja palvelimien välinen pyyntö ei voi koskaan läpäistä selainhaastetta, joten sekä Test-painike että todelliset tapahtumat epäonnistuvat samalla tavalla. Test-painike kertoo sinulle, kun näin tapahtuu (“Cloudflare is showing a bot challenge to our request”). Korjaa asia Cloudflaressa Security / WAF-säännöllä, joka ohittaa haasteet webhook-polullesi (tai Webhook-Delivery/1.0-käyttäjäagentille), ja napsauta sitten Test uudelleen.
• Jos palomuurisi vaatii sen sijaan IP-sallittujen luettelon (esimerkiksi Cloudflaren ilmaisessa paketissa, jossa tavallista Bot Fight Modea ei voi ohittaa WAF-säännöllä, mutta sallittuun IP-pääsysääntöön asetettu sääntö toimii sitä ennen), voimme auttaa: jokainen toimitus, olipa se peräisin Test-painikkeesta tai live-tapahtumasta, lähetetään yhdestä kiinteästä IPv4-osoitteesta (ei vaihteluvälejä, ei IPv6:ta, ei vaihtuvuutta). Ota yhteyttä tukeen, niin annamme sinulle osoitteen sallittujen luetteloon lisäämistä varten. Pidä allekirjoituksen varmentaminen varsinaisena luottamustarkistuksenasi, sillä se vahvistaa jokaisen hyötykuorman riippumatta siitä, mistä se on peräisin.
• Testin tulos kertoo tarkalleen, mitä päätepisteesi vastasi. Epäonnistunut testi näyttää nyt todellisen syyn (päätepisteesi palauttaman HTTP-tilan, aikakatkaisun tai sen, ettemme tavoittaneet osoitetta lainkaan) yleisen virheen sijaan, ja tallennetulle webhookille tehty testi lähetetään allekirjoitettuna, kun allekirjoitus on käytössä, aivan kuten live-tapahtumassa.

n8n:n, Make:n tai Zapierin käyttäminen (“Test URL” vs “Production URL”) #

Automaatioalustat tarjoavat yleensä kaksi eri webhook-osoitetta, mikä aiheuttaa usein sekaannusta:

• Testi-URL (n8n:ssä se sisältää /webhook-test/). Tämä vastaanottaa tietoja vain silloin, kun tarkkailet työtilaa aktiivisesti ja olet juuri napsauttanut Kuuntele testitapahtumaa (tai Testaa työnkulkua). Se tallentaa yhden tapahtuman ja lopettaa sitten kuuntelun – joten Testaa-painikkeen napsauttaminen Your AI Connector-kohdassa useita kertoja peräkkäin tallentaa vain ensimmäisen, ja vain jos kuunteluikkuna on aktiivinen juuri sillä hetkellä. Testaa näin: napsauta ensin Kuuntele testitapahtumaa n8n:ssä, palaa sitten Your AI Connector-kohtaan ja napsauta Testaa kerran.
• Tuotanto-URL (n8n:ssä se sisältää /webhook/, ei -test). Tämä on osoite, joka liitetään Your AI Connector-kohtaan live-tapahtumia varten. Se toimii vasta, kun työnkulkusi on asetettu tilaan Aktiivinen. Jos työnkulku ei ole aktiivinen, n8n hylkää pyynnön virheellä “404 / webhook not registered”, vaikka Your AI Connector lähetti tiedot oikein.

Lyhyesti: testaa Test-URL:lla kuuntelun aikana, mutta jotta webhook toimisi jatkossakin oikeiden yhteystietojen kanssa, tallenna Tuotanto-URL kohtaan Your AI Connector ja varmista, että työnkulku on Active.

Webhook-tietomuoto #

Kun webhook laukeaa, Your AI Connector lähettää jäsenneltyä tietoa (JSON) webhook URL-osoitteeseesi. Jos käytät automaatioalustaa, kuten Zapieria tai Makea, se jäsentää nämä tiedot puolestasi automaattisesti. Jos rakennat mukautettua integraatiota:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

campaign tai agent — yleensä toinen, ei molemmat. Jos tilisi käyttää agentteja, yhteyshenkilösi ovat agentin eivätkä kampanjan hallinnassa, joten campaign saapuu muodossa null ja agent kertoo, kuka niitä käsitteli. Vanhemmat kampanjapohjaiset tilit näkevät tämän päinvastoin. Lue se kenttä, joka on täytetty; älä oleta, että campaign on aina olemassa.

agent-lohko saapui 15. elokuuta 2026. Se sijaitsee campaign-kohdan rinnalla keskusteluun liittyvissä tapahtumissa – päättynyt keskustelu, älä häiritse -tila, jatkaminen, arkiston purku, tekoälyn tauottaminen, uusi viesti, keskustelun yhteenveto ja tunnisteeseen asetettava webhook – ja se sisältää käsittelevän agentin id- ja name-tiedot tai null-arvon, kun agenttia ei ole mukana. Se on täysin lisäluonteinen: jokainen jo vastaanottamasi kenttä pysyy muuttumattomana, joten ennen kyseistä päivämäärää rakentamasi vastaanotin toimii edelleen ilman päivitystarvetta.

Jotkut tapahtumat lisäävät oman ylimmän tason lohkonsa. Esimerkiksi Appointment Booked (Aika varattu) lisää appointment-lohkon (katso Appointment Booked Webhook), New Message (Uusi viesti) lisää täyden message-lohkon teksteineen (katso New Message Webhook), ja Deliveries (Toimitukset) sekä Reads (Luetut) lisäävät lyhyen message-lohkon, joka sisältää vain viestin tunnisteen ja tilan (katso Deliveries and Reads Webhook).

Deliveries- ja Reads-tapahtumat kertovat, mikä viesti on kyseessä, mutta eivät sen sisältöä. Ne sisältävät message-lohkon, jossa on viestin id ja status — ja tämä id on sama messageId, jonka lähetä viesti -päätepiste palauttaa, joten voit yhdistää toimitus- tai lukukuittauksen juuri lähettämääsi viestiin — mutta viestin runko puuttuu. Replies (Vastaukset) ei sisällä lainkaan message-lohkoa. Jos tarvitset lähetettyjä tai vastaanotettuja sanoja, tilaa niiden lisäksi New Message.

Kaksi asiaa, jotka on hyvä tietää ennen vastaanottimen kirjoittamista. Siinä ei ole timestamp-kenttää eikä data-käärettä. Jokainen lohko sijaitsee JSON-objektin ylimmällä tasolla, kuten yllä on esitetty.

22 webhook-tapahtumaa #

22 webhook-tapahtumaa, näyttönimi, jonka valitset sovelluksessa, ja hyötykuormassa lähetettävä event-koodi. event-koodi on lyhyt merkkijono, joka ei vastaa näyttönimeä, joten määritä vastaanottimesi koodin, ei nimen perusteella:

Kaksi muuta koodia ei koskaan näy kyseisessä luettelossa, koska et tilaa niitä: contact_tags_updated, jonka lähettää yksittäiselle tunnisteelle asetettu webhook-URL, ja summary_generated, joka lähetetään, kun keskusteluyhteenveto kirjoitetaan tunnisteelle webhookin subscribed_to_tags-luettelossa.

Kanava yhdistetty -tapahtumaa ei vielä lähetetä. Se näkyy tapahtumaluettelossa, mutta mikään ei lähetä sitä tällä hetkellä. Älä rakenna toiminnallisuutta sen varaan.

Tunnisteisiin ja tehtäviin perustuvat ilmoitukset käyttävät omia erillisiä muotojaan. Katso Contact Tags Updated ja Task Completed.

Yhteystieto luotu -webhook #

Lähetetään, kun Yhteystieto luotu -tapahtuma laukeaa (uusi yhteystieto lisätään manuaalisesti, tuonnin kautta tai API:n kautta).

Tapahtuman nimi #

contactCreated

Hyötykuorman muoto #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

“Testi”-näyte ja todellinen tapahtuma näyttävät hieman erilaisilta. Testipainike lähettää paikkamerkkitietoja (John Doe, esimerkkikampanja). Todellinen “Yhteystieto luotu” -tapahtuma sisältää yhteystiedon todelliset tiedot, ja jotkin kentät voivat olla tyhjiä kanavasta riippuen.

New Message Webhook #

Tämä webhook laukeaa joka kerta, kun viesti lisätään keskusteluun millä tahansa kanavalla. Se kattaa molemmat suunnat: yhteystiedon sinulle lähettämät viestit sekä tekoälyn, tiimisi tai kampanjan heille lähettämät viestit. Se on ainoa webhook, joka sisältää viestitekstin, joten käytä tätä, kun haluat peilata keskusteluja ulkoiseen järjestelmään.

Tapahtuman nimi #

new_message

Hyötykuorman muoto #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web"
  }
}

Tässä hyötykuormassa ei ole vieläkään campaign-lohkoa. New Message lähettää contact-, agent-, user- ja message-tiedot. agent-lohko lisättiin 15. elokuuta 2026, ja se kertoo, mikä agentti käsittelee keskustelua; jos tarvitset myös kampanjakontekstia, etsi yhteyshenkilö API:n kautta käyttämällä contact.id-tunnistetta.

Sisäiset tekoälytietueet eivät laukaise tätä webhookia. Todellisten viestien ohella alusta pitää omia kirjanpitorivejään keskustelussa (tekoälyn työkalukutsut ja sisäiset vuorotietueet). Niitä ei koskaan lähetetä — vastaanotat vain viestit, jotka on todellisuudessa lähetetty tai vastaanotettu.

Deliveries and Reads Webhook #

Nämä kaksi tapahtumaa raportoivat, mitä viestille tapahtui sen jälkeen, kun se lähti Your AI Connector-päätepisteestä: Deliveries laukeaa, kun viesti saavuttaa yhteystiedon (tai epäonnistuu), ja Reads laukeaa, kun yhteystieto avaa sen, niillä kanavilla, jotka tukevat lukukuittauksia.

Molemmat sisältävät message-lohkon, jossa on tapahtumaa koskevan viestin tunniste, joten voit yhdistää päivityksen juuri lähettämääsi viestiin.

Tapahtumien nimet #

delivered ja undelivered tapahtumalle Deliveries, read tapahtumalle Reads.

Hyötykuorman muoto #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Kuinka yhdistää päivitys lähettämääsi viestiin. Tallenna messageId, jonka saat takaisin, kun lähetät viestin API:n kautta. Kun Deliveries- tai Reads-ilmoitus saapuu, etsi kyseinen tallennettu tunniste hyötykuorman message.id-kentästä — se on kyseisen viestin toimitus- tai lukukuittaus.

Tässä ei ole viestitekstiä. message-lohko sisältää vain tunnisteen ja tilan. Tilaa New Message, jos tarvitset myös viestin rungon.

message-lohko on läsnä vain, kun tiedämme, mikä viesti on kyseessä. Harvinaisissa päivityksissä, joita emme voi yhdistää tallennettuun viestiin, lohko jätetään kokonaan pois sen sijaan, että se lähetettäisiin tyhjänä — tarkista siis, että message on olemassa ennen kuin luet message.id-kentän.

Yksi ilmoitus per tilan muutos. Yksittäinen lähtevä viesti tuottaa yleensä delivered-ilmoituksen ja sen jälkeen, lukukuittauksia tukevilla kanavilla, read-ilmoituksen. Epäonnistunut lähetys tuottaa sen sijaan undelivered-ilmoituksen.

Appointment Booked Webhook #

Laukeaa, kun yhteystieto varaa ajan. Se laukeaa samalla tavalla riippumatta siitä, varasiko tekoäly ajan keskustelun aikana, varasitko sen käsin vai tuliko se API:n kautta.

Tapahtuman nimi #

booked

Hyötykuorman muoto #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id on tässä webhookissa usein null, ja se on normaalia. Google Kalenterin tapahtuma luodaan samalla hetkellä, kun tämä ilmoitus lähtee, joten tunniste ei yleensä ole vielä valmis. Hae varaus uudelleen sen appointment_id-tunnisteella hetken kuluttua, jos tarvitset sitä. Se pysyy pysyvästi null-arvossa, jos tilille ei ole yhdistetty Google Kalenteria, joten älä odota sitä loputtomiin.

“Testi”-painike ei sisällä appointment-lohkoa. Käytä sitä varmistaaksesi, että päätepisteesi vastaa, ja tee sitten yksi todellinen varaus nähdäksesi koko hyötykuorman.

Kaksi tapausta, joissa tämä webhook ei laukea: ulkoisesta kalenterista tuodut tapaamiset ja Formitable-integraation kautta tulevat varaukset.

Yhteystietotunnisteiden päivityksen webhook #

Käynnistyy, kun tunniste lisätään yhteystietoon ja kyseiselle tunnisteelle on määritetty webhook-URL-osoite agentissa tai kampanjassa, johon yhteystieto kuuluu.

Tapahtuman nimi #

contact_tags_updated

Milloin se laukeaa #

• Tunniste lisätään yhteystietoon, jolle on määritetty agentti, kampanja tai molemmat.
• Ainakin yhdelle lisätyistä tunnisteista on määritetty webhook-URL-osoite kyseisen agentin tai kampanjan Tunnisteet-välilehdellä.

Jos yhteystiedolla on molemmat ja kampanjan tunnisteissa on webhook-URL-osoitteet, ne ovat ensisijaisia; muussa tapauksessa käytetään agentin tunnisteita.

Jos samassa päivityksessä lisätään useita tunnisteita, joilla on eri webhook-URL-osoitteet, jokaiselle URL-osoitteelle lähetetään yksi pyyntö, joka sisältää vain kyseiseen URL-osoitteeseen liittyvät tunnisteet.

Tunnisteen poistaminen ei koskaan lähetä pyyntöä. Useimmat käyttäjät ohjaavat nämä URL-osoitteet toimintoon – kuten talletuksen keräämiseen, ajan varaamiseen tai edustajan hälyttämiseen – joten tunnisteen poistaminen yhteystiedosta voisi käynnistää toiminnon uudelleen. Näin ei enää tapahdu. Poisto näkyy edelleen kohdassa removed_tags, kun se tapahtuu samassa päivityksessä kuin lisäys, joka menee samaan URL-osoitteeseen, joten molempia taulukoita lukeva automaatio säilyttää täyden tilannekuvan; se ei kuitenkaan koskaan näe pelkän poiston aiheuttamaa pyyntöä. (Muutettu 12. elokuuta 2026. Sitä ennen poistot lähettivät myös pyynnön.)

Hyötykuorman muoto #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    }
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Tunnisteen webhookin testaaminen #

Tunnisteet-välilehden webhook-URL-kentän vieressä on Testaa-painike. Se lähettää näytehyötykuorman kyseiseen URL-osoitteeseen välittömästi, jotta voit varmistaa automaatiosi vastaanottavan sen ennen kuin odotat todellista keskustelua.

Testi lähettää saman contact_tags_updated-muodon, joka näkyy yllä, käyttäen paikkamerkkiyhteystietoa, testattavaa tunnistetta kohdassa added_tags ja tyhjää removed_tags-kenttää. Se, mitä automaatiosi näkee testissä, on sama, mitä se näkee tuotannossa.

Kaksi asiaa, jotka on hyvä tietää:

• Tallenna tunniste ensin. Testi etsii tunnisteen sen tallennetun nimen perusteella, joten upouutta tunnistetta tai tallentamatonta nimenmuutosta ei voi vielä testata. Painike pysyy harmaana, kunnes näytöllä oleva nimi vastaa tallennettua nimeä.
• Epäonnistunut testi ei vaikuta webhookiisi. Testit eivät koskaan vaikuta automaattiseen poiskytkentään toistuvien epäonnistumisten jälkeen, kuten kohdassa Webhookin luotettavuus on kuvattu.

Jos testi epäonnistuu, viesti kertoo, mitä päätepisteesi vastasi (esimerkiksi 404 tai 500), mikä yleensä riittää väärän URL-osoitteen tai pois päältä olevan työnkulun tunnistamiseen.

Tehtävän suorittamisen webhook #

Vain viitteeksi. Tehtävä-webhookit (datana) on dokumentoitu tässä kehittäjiä varten; Tehtävä luotu, Tehtävä päivitetty ja Tehtävä suoritettu -tapahtumat ovat valittavissa webhook-lomakkeen tavallisessa tapahtumaluettelossa kuten mikä tahansa muu tapahtuma – katso Käytettävissä olevat käynnistystapahtumat ja 22 webhook-tapahtumaa.

Tämä hyötykuorma lähetetään, kun tehtävä siirtyy vaiheeseen, joka on merkitty suoritusvaiheeksi. Tehtävä, joka liikkuu muiden kuin suoritusvaiheiden välillä, lähettää sen sijaan taskUpdated-muodon.

Tapahtuman nimi #

taskCompleted

Milloin se laukeaa #

• Tehtävä päivitetään.
• Sen stage-arvo muuttui verrattuna edelliseen arvoonsa.
• Uusi vaihe on määritetty suoritusvaiheeksi tilin tehtävävaiheasetuksissa.

Hyötykuorman muoto #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Webhookin poistaminen käytöstä (tai poistaminen) #

Jokaisella webhookilla on päälle/pois-kytkin suoraan sen rivillä. Sen kytkeminen pois päältä estää tapahtumien vastaanottamisen, mutta säilyttää kaiken määrittämäsi — URL-osoitteen, tapahtumat ja mahdollisen allekirjoitussalaisuuden. Kytke se takaisin päälle, niin se jatkaa siitä, mihin se jäi; mitään sen ollessa pois päältä tapahtunutta ei toimiteta jälkikäteen.

Käytä tätä, kun haluat keskeyttää toimitukset hetkeksi: päätepistettäsi rakennetaan uudelleen, vianmäärität häiriöitä aiheuttavaa integraatiota tai keskeytät automaation.

Webhookin poistaminen (roskakorikuvake sen rivillä) poistaa sen pysyvästi, mukaan lukien sen allekirjoitussalaisuuden. Jos haluat vain estää toimitukset, kytke se sen sijaan pois päältä — poisto on tarkoitettu tilanteisiin, joissa olet valmis päätepisteen kanssa kokonaan.

Tämä ei ole sama asia kuin webhookin kytkeminen automaattisesti pois päältä. Jos poistamme webhookisi käytöstä toistuvien virheiden vuoksi (katso Webhookin luotettavuus), yllä oleva valitsin ei palauta sitä. Kun päätepisteesi on korjattu, muokkaa webhookia ja tallenna se muutetulla URL-osoitteella (mikä tahansa URL-osoitteen muutos aktivoi sen uudelleen), tai kutsu uudelleenaktivointipäätepistettä API:n kautta – tai pyydä tukea, niin kytkemme sen takaisin puolestasi.

Allekirjoitetut hyötykuormat (Webhookin alkuperän varmentaminen) #

Kuka tahansa, joka saa selville webhook-URL-osoitteesi, voi lähettää siihen valepyyntöjä. Jos toimit webhookien perusteella automaattisesti — päivität laskutusta, luot CRM-tietueita — allekirjoituksen käyttöönotto antaa sinun varmistaa, että jokainen pyyntö tuli aidosti meiltä.

Allekirjoitus on valinnainen ja oletusarvoisesti pois päältä, ja kytket sen päälle webhook-kohtaisesti kyseisen webhookin muokkausnäkymästä (avaa tallennetun webhookin rivi).

Allekirjoituksen käyttöönotto #

1. Avaa webhook (Asetukset → Integraatiot → Webhookit → napsauta webhookisi riviä).
2. Napsauta Allekirjoitussalaisuus-osiossa Luo.
3. Kopioi salaisuus (se alkaa merkeillä whsec_) ja tallenna se vastaanottavaan järjestelmääsi. Käsittele sitä kuin salasanaa.

Voit palata takaisin ja paljastaa, kopioida, vaihtaa tai kytkeä salaisuuden pois päältä milloin tahansa samasta paneelista.

Mitä lähetämme #

Kun allekirjoitus on käytössä, jokainen webhook-toimitus sisältää nämä kaksi ylimääräistä HTTP-otsikkoa:

Nämä kolme ovat mukana jokaisessa toimituksessa, riippumatta siitä, onko se allekirjoitettu vai ei:

Miten varmentaminen tapahtuu #

Allekirjoitus on HMAC-SHA256-tiiviste merkkijonosta <timestamp>.<raw request body>, jossa käytetään allekirjoitussalaisuuttasi avaimena.

Varmista raaka pyyntörunko — täsmälleen ne tavut, jotka vastaanotit. Jos kehys jäsentää JSON-tiedoston ja sarjallistaa sen uudelleen ennen tarkistusta, tavut voivat muuttua eikä allekirjoitus täsmää.

Node.js-esimerkki:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Python-esimerkki:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Vertaa allekirjoituksia ajoitusturvallisella funktiolla (timingSafeEqual / compare_digest), älä ==. Se ei maksa mitään ja estää hienovaraisen hyökkäysluokan.

Salaisuuden vaihtaminen #

Napsauta Vaihda (Rotate) korvataksesi salaisuuden. Vaihto tapahtuu välittömästi: heti seuraava lähetys allekirjoitetaan vain uudella salaisuudella. Jos päätepisteesi on käytössä, hyväksy sekä vanha että uusi salaisuus muutaman minuutin ajan, kunnes olet ottanut uuden käyttöön.

Allekirjoituksen poistaminen käytöstä estää vain allekirjoitusotsikoiden lähettämisen.

Epäonnistuneiden lähetysten uudelleenyritykset #

Oletusarvoisesti epäonnistunutta lähetystä ei yritetä uudelleen — jos järjestelmäsi on kyseisellä hetkellä alhaalla, kyseinen tapahtuma jää väliin.

Ota käyttöön Yritä epäonnistuneet lähetykset uudelleen webhookissa (luonti-/muokkauslomakkeessa), niin jatkamme yrittämistä:

Tämä kestää yhteensä noin 2 tuntia ja 40 minuuttia, joten webhook selviää huoltokatkosta tai lyhyestä käyttökatkosta päässäsi.

Mitä yritetään uudelleen: väliaikaiset ongelmat — palvelimesi palauttaa 5xx-virheen, aikakatkaisu tai yhteysvirhe.

Mikä ei onnistu: jos päätepisteesi hylkää itse pyynnön (mikä tahansa 4xx-virhe), emme yritä uudelleen – identtisen pyynnön lähettäminen uudelleen tuottaisi vain saman hylkäyksen.

Mitkä tapahtumat yritetään uudelleen: tunnisteiden webhookit (contact_tags_updated), kolme tehtävätapahtumaa ja päivittäinen yhteenveto. Muut lähetetään vain kerran, joten niiden kohdalla kytkimellä ei ole vaikutusta. Jokainen tapahtuma sisältää silti X-Webhook-Delivery-tunnisteen, joten yksi duplikaattien poistamissääntö kattaa ne kaikki.

Ota uudelleenyritykset käyttöön vain, jos päätepisteesi on idempotentti. Uudelleenyritykset tarkoittavat, että sama tapahtuma voi saapua useammin kuin kerran. Käytä X-Webhook-Delivery-otsikkoa toiston tunnistamiseen: se pysyy samana jokaisessa yrityksessä yhden tapahtuman kohdalla, joten voit turvallisesti jättää huomiotta tunnisteen, jonka olet jo käsitellyt.

Uudelleenyritykset toimivat toistuvien epäonnistumisten jälkeisen automaattisen poiskytkennän kanssa (katso Webhookin luotettavuus) juuri niin kuin haluat: epäonnistumislaskuri laskee kokonaisen toimituksen vasta sen jälkeen, kun jokainen uudelleenyritys on käytetty — ei jokaista yksittäistä yritystä.

Webhookin luotettavuus #

• Your AI Connector lähettää webhookit suojatun yhteyden (HTTPS) kautta. Varmista, että antamasi verkko-osoite käyttää HTTPS-protokollaa.
• Jos järjestelmäsi palauttaa virheen, toimitus katsotaan epäonnistuneeksi.
• Seuraa vastaanottavan järjestelmäsi käytettävyyttä välttääksesi tapahtumien menettämisen.
• Kriittisiä työnkulkuja varten ota käyttöön Epäonnistuneiden toimitusten uudelleenyrittäminen ja harkitse myös varamekanismia.

Webhookit kytkeytyvät automaattisesti pois päältä toistuvien virheiden jälkeen. Jos webhook-URL-osoitteesi epäonnistuu toistuvasti (noin 5 virhettä peräkkäin tai 3 peräkkäistä konfiguraatiovirhettä), Your AI Connector lopettaa automaattisesti tapahtumien lähettämisen kyseiseen URL-osoitteeseen. Kun päätepisteesi on taas kunnossa, voit palauttaa sen toimintaan seuraavasti: muokkaa webhookia ja tallenna se muutetulla URL-osoitteella (mikä tahansa URL-osoitteen muutos aktivoi sen uudelleen), tai käytä uudelleenaktivointipäätepistettä API:n kautta – pelkkä uudelleentallennus samalla URL-osoitteella ei riitä. Myös tuki voi aktivoida sen puolestasi.

Vianmääritys #

Seuraavat vaiheet #

• GoHighLevel-integraatio — käytä webhookeja Your AI Connector-palvelun integroimiseen GHL:n kanssa.
• API-käyttöoikeus — yhdistä webhookit ja API tehokkaita automaatioita varten.
• Tunnisteiden käyttäminen yhteystietojen merkitsemiseen — määritä tunnisteita, jotka laukaisevat webhookisi.