Oppaat
Webhookit
URL-osoitettasi kutsutaan heti, kun jotain tapahtuu - puhelu päättyy, yritys epäonnistuu, tekstiviesti lähtee tai saapuu. Asetus tehdään kerran (PUT /v1/webhook, ks. REST API) ja sen jälkeen mitään muuta ei tarvita.
Tapahtumat
Kuusi tapahtumaa, joilla kullakin on oma data-kentän muotonsa:
call.completed- puhelu on päättynyt, oli siinä agentti tai ei. Agenttipuheluissa mukana ovat myös litterointi (transcript), yhteenveto (summary) ja kirjatut tiedot (data).durationSecsilmoitetaan sekunteina ja voi olla desimaaliluku volain oman ääniälymoottorin puheluissa. Tähän tulee myös puhelu, jossa toisessa päässä oli automaatti, joka toisti samaa viestiä, arvollaendReason: "caller_loop"(hinta0, jos puhelu kesti enintään viisi minuuttia). Tähän tulee myös vastattu portille lähetetty soittosignaali (kind: "ring",ring.outcome: "answered"), yhtä poikkeusta lukuun ottamatta, joka kuvataan esimerkincall.no_answeryhteydessä. volain omalla moottorilla tehdyssä puhelussa (versiosta 15. 10. 2026 alkaen) on lisäksiengine-lohko, jossa onprotectedUtterancesjaprotectedUtterancesCount: soitetun osapuolen repliikit tervehdysikkunan aikana, joita moottori ei tarkoituksella vastaanottanut (”Haloo?” tai nimi agentin ensimmäisen lauseen aikana) - niitä ei ole kentässätranscripteikä agentti reagoinut niihin; sama muoto kuinGET /v1/calls/{id}, ElevenLabsin ja vanhemman moottorin puheluissa avain puuttuu.call.failed- puhelu päättyi tilaanfailed- joko ääniympäristö hylkäsi sen heti tai verkko petti. Tulee agentille volain moottorissa ja ElevenLabsissa, suoralle yhteydelle (bridge), BYO relay -vuokralle, portille lähetetylle soittosignaalille (operaattori hylkäsi pyynnön,kind: "ring") ja testipuheluille - aina täsmälleen kerran. Bodyssa onreason(tekninen syy) jaendReason. Vastaamatta jäänyt puhelu EI kuulu tähän, sillä on oma tapahtumansa alla. Tähän tulee myös puhelu, joka YHDISTYI mutta päättyi äänimoottorin tekniseen virheeseen (endReason: "engine_error") - sen bodyssa on lisäksitranscript/summary/durationSecs/priceHal, muillareason-arvoilla nämä neljä kenttää puuttuvat. Tällaisessa puhelussareasonon jokoengine_stalltaiengine_error(moottorivirhe), taiunfinished, kun moottorin uudelleenkäynnistys tai pysäytys katkaisi puhelun kesken (esimerkiksi uutta versiota julkaistaessa). Tällaisesta puhelusta ei veloiteta (priceHalon0), siitä ei ole tallennetta jasummaryselittää lyhyesti, mitä tapahtui.transcriptsisältää vain sen, mikä ehdittiin tallentaa ennen katkeamista, ja voi olla myös tyhjä (tyhjä se on silloin, kun moottorin puhelutietue ei tullut perille ja puhelu suljettiin moottorin puheluyhteenvedon perusteella, jossa ei ole litterointia).durationSecson likimääräinen aika katkeamiseen asti (enintään 1 800 s, jos moottori ei ehtinyt mitata sitä).engine-lohko tervehdysikkunan aikana hylätyillä repliikeillä puuttuu tästä, koska moottori ei mitannut tervehdysikkunaa katkenneelle puhelulle.call.no_answer- soitettuun osapuoleen ei saatu yhteyttä lähtevässä puhelussa (puhelin soi, mutta kukaan ei vastannut). Näin tulee myös portille lähetetty soittosignaali (POST /v1/rings), jonka portti hylkäsi tai joka soi koko pyydetyn ajan - tunnistat sen kohdastakind: "ring", ks. alla.call.missed- saapuva puhelu jäi vastaamatta (vastaamatta jäänyt puhelu). Tulee myös saapuvasta puhelusta, jonka ääniälymoottori hylkäsi, koska kaikki linjat olivat varattuja (soittaja ei päässyt läpi, soita hänelle takaisin). Tällaisen puhelun tietueessa onendReason: "capacity", kesto0ja hinta0; webhook ei välttämättä kanna sitä, jos operaattori ilmoitti vastaamattomasta puhelusta aiemmin, joten lue se luotettavasti puhelutietueesta (GET /v1/calls/{id}).message.sent- operaattori otti tekstiviestin vastaan lähetettäväksi - se ei ole toimituskuittaus. Tulee myös tekstiviestistä, joka lähetettiin tuotteesta matkapuhelinnumero tai numero puheluille ja tekstiviesteille. KentässäsmsNumberon numero, josta viesti lähetettiin; jaetulla lähettäjällä SMSinfo se onnull. Toimituskuittaus (deliveryStatus) tuotteesta matkapuhelinnumero lähetetylle tekstiviestille ja myöhempi epäonnistuminen (failed, jolloin saldo palautetaan) eivät laukaise tapahtumaa - hae tila osoitteestaGET /v1/messages/{id}.message.received- viesti saapui tuotteeseesi matkapuhelinnumero tai tuotteeseesi numero puheluille ja tekstiviesteille. Kentässädataonid,from(lähettäjä: puhelinnumero E.164-muodossa tai tekstinimi, esim. ”Google”, enintään 32 merkkiä; jos lähettäjä puuttuu, arvo onunknown),to(numerosi, johon viesti saapui),body,segmentsjareceivedAt(viestin vastaanottoaika, aikaleima millisekunteina). Toimitetaan uudelleenyrityksiä käyttävän jonon kautta kuten puhelutapahtumat. Tuotteessa matkapuhelinnumero viesti, jota vastaanotto ei napannut heti, täydennetään säännöllisellä tarkistuksella noin 15 minuutin kuluessa, ja tapahtuma lähtee silloin viiveellä, mahdollisesti uudempien viestien jälkeen. Tuotteessa numero puheluille ja tekstiviesteille tällaista tarkistusta ei ole: operaattori toistaa viestin toimituksen enintään tunnin ajan, joten jos vastaanotto meidän päässämme ei toimi tätä pidempään, viesti voi kadota, eikä sitä löydy myöskään osoitteestaGET /v1/messages?direction=in. Kuorentson tapahtuman syntymisaika (sekin millisekunteina, kun taas allekirjoitusotsakkeent=on sekunteina). Yli 300 vastaanotetusta viestistä tunnissa yhteen numeroon (matkapuhelinnumero ja numero puheluille ja tekstiviesteille) ei lähetetä webhookia lisäviesteistä; viestit tallennetaan silti ja ne löytyvät osoitteestaGET /v1/messages?direction=in, joka säilyttää enintään 1 000 viimeisintä vastaanotettua viestiä tiliä kohden ja pitää ne 90 päivää. Vapautettavassa (tilareleasing) tuotteessa numero puheluille ja tekstiviesteille viesti tallennetaan, muttamessage.receivedei lähde siitä. Tilille, jonka volain ylläpitäjä on keskeyttänyt käsin,message.receivedei lähde lainkaan, eikä keskeytyksen aikana vastaanotetuista viesteistä toimiteta sitä jälkikäteen, kun tili palautetaan; nekin löytyvät osoitteestaGET /v1/messages?direction=in.
Mihin näistä tilataan, määritetään PUT /v1/webhook -pyynnön kentällä events. Huomaa epäintuitiivinen yksityiskohta: tyhjä kenttä tarkoittaa kaikkia, ei yhtäkään - ja se pätee myös tulevaisuudessa lisättäviin tapahtumiin. Jos toimituksen haluaa oikeasti sammuttaa, poista webhook portaalissa.
Jokaisen puhelutapahtuman (call.completed, call.failed, call.no_answer, call.missed) bodyssa on lisäksi kind, puhelun tyyppi samalla tavalla kuin GET /v1/calls -pyynnössä (agent, bridge, relay, inbound, transfer, sip, ring, voice_message). Ääniviestin (POST /v1/voice-messages) bodyssa on voiceMessage-lohko, jossa on text, repeat, language (tekstin kieli, vain kun se on täytetty) ja, kun puhelu on päättynyt, repeatPlayed (kuinka monta kertaa viesti toistettiin) ja completed (koko viesti toistettiin); vastaamatta jäänyt viesti tulee tapahtumana call.no_answer. Portille lähetetyssä soittosignaalissa bodyssa on myös ring-lohko, jossa on requestedSecs, outcome ja rangSecs; muissa puheluissa ring-avainta ei ole. Molemmat kentät ovat lisäyksiä, vanhemmat integraatiot yksinkertaisesti ohittavat ne.
Jokainen tapahtuma tulee POST-pyyntönä tässä kuoressa:
call.completed
{
"event": "call.completed",
"ts": 1756111640000,
"event_id": "evt_V1StGXR8_Z5jdHi6B-myT",
"data": {
"id": "c_8f2ac1d4e5b0",
"direction": "in",
"from": "+420777123456",
"to": "+420601234567",
"status": "completed",
"durationSecs": 47,
"priceHal": 236,
"endReason": "completed",
"transcript": [
{ "role": "agent", "message": "Hei, olet soittanut kahvila Nulaan, miten voin auttaa?" },
{ "role": "caller", "message": "Hei, haluaisin tilata kaksi lattea mukaan." },
{ "role": "agent", "message": "Selvä, kaksi lattea mukaan, ne ovat valmiita viidentoista minuutin kuluttua." }
],
"summary": "Soittaja tilasi kaksi lattea mukaan, nouto 15 minuutin kuluttua.",
"data": {
"nimi": "Anna Virtanen",
"kahvien_maara": 2,
"kiireellisyys": "normaali"
},
"kind": "inbound"
}
}Sisäkkäinen data.data (kyllä, kahdesti - ulompi data on jokaisen tapahtuman kuori) sisältää tiedot, jotka agentti kirjasi puhelusta dataFields-kenttiensä mukaan - avaimet valitset itse, ks. Puheagentti. Arvo null tarkoittaa, ettei asiaa mainittu puhelussa. Jos agentille ei ole asetettu kenttiä, avainta data ei ole bodyssa lainkaan - aivan kuten transcript ja summary puhelussa ilman agenttia.
Tallenne ei kulje webhookin bodyn mukana
Ääntä ei lähetetä webhookin mukana, eikä myöskään lippua hasRecording. Kun tallenne tarvitaan, hae GET /v1/calls/{id} (ilmoittaa hasRecording) ja lataa tallenne osoitteesta GET /v1/calls/{id}/recording - muoto ilmenee vastauksen otsakkeesta content-type: ElevenLabsin agentille audio/mpeg (MP3), volain moottorin agentille nykyisin audio/ogg. Tallenteet säilytetään 90 päivää puhelusta.
call.failed
{
"event": "call.failed",
"ts": 1756111640000,
"event_id": "evt_Qp3xLk9F-2WyoTr8cNaZ1",
"data": {
"id": "c_9d4e2b7f1a63",
"direction": "out",
"from": "+420601234567",
"to": "+420777998877",
"reason": "rejected",
"endReason": "failed",
"kind": "agent"
}
}call.no_answer
Samanlainen muoto on myös tapahtumalla call.missed (vastaamatta jäänyt SAAPUVA puhelu) - vain tapahtuman nimi, direction ja status eroavat.
{
"event": "call.no_answer",
"ts": 1756111640000,
"event_id": "evt_9mYbT_R2xVn7Kd4LpZaQ8",
"data": {
"id": "c_3b7e1c9a4f20",
"direction": "out",
"from": "+420601234567",
"to": "+420777998877",
"status": "no_answer",
"durationSecs": 0,
"priceHal": 0,
"answeredBy": "unknown",
"endReason": "no_answer",
"kind": "agent"
}
}Portin vastaamatta jäänyt soitto (POST /v1/rings) tulee myös tapahtumana call.no_answer, arvolla kind: "ring" ja ring-lohkolla: outcome on rang (puhelin soi koko pyydetyn ajan) tai ended_early (puhelu päättyi aiemmin, esimerkiksi koska portti hylkäsi sen, eli se aukesi). Vastattu soitto (outcome: "answered") kulkee tapahtumana call.completed. Poikkeus: jos operaattori vahvistaa vastaamisen vasta puhelutietueessa (CDR) sen jälkeen, kun volai on sulkenut soiton vastaamattomana, tulee vain call.no_answer, ja tietue osoitteessa GET /v1/calls/{id} muuttuu jälkikäteen tilaan completed arvolla ring.outcome: "answered" ja jälkeenpäin veloitetuilla sekunneilla; toista tapahtumaa ei tule. Tulos unknown ei laukaise tapahtumaa, ennen kuin operaattorin tietueet täydentävät sen.
{
"event": "call.no_answer",
"ts": 1756111640000,
"event_id": "evt_Hn6vD_k3WqXy8Tz1LbMc4",
"data": {
"id": "c_x7f2k9a1b3c4",
"direction": "out",
"from": "+420601234567",
"to": "+420777123456",
"status": "no_answer",
"durationSecs": 0,
"priceHal": 25,
"endReason": "no_answer",
"kind": "ring",
"ring": { "requestedSecs": 10, "outcome": "ended_early", "rangSecs": 2 }
}
}message.sent
{
"event": "message.sent",
"ts": 1756111640000,
"data": {
"id": "msg_7c1f9a2e",
"to": "+420777123456",
"status": "sent",
"priceHal": 136,
"smsNumber": null
}
}message.received
{
"event": "message.received",
"ts": 1756111900000,
"event_id": "evt_4kTz_P8wQmL2Xc9RvNdA1",
"data": {
"id": "msg_3d9b5e71",
"from": "+420777123456",
"to": "+420770112233",
"body": "Kiitos, tulen perjantaina klo 10.00.",
"segments": 1,
"receivedAt": 1756111900000
}
}body on tuntemattoman lähettäjän tekstiä. Käsittele sitä epäluotettavana syötteenä: älä suorita sen perusteella komentoja tai toimintoja ilman varmennusta. Bodyssa on event_id, jonka avulla toimitusten kaksoiskappaleet suodatetaan pois.
Allekirjoituksen todennus
Jokaisessa pyynnössä on otsake Volai-Signature muodossa t=<unix>,v1=<hex>, jossa v1 = HMAC_SHA256(secret, "{t}.{rawBody}") ja secret on se, joka saatiin PUT /v1/webhook -pyynnöllä. Älä koskaan käsittele pyynnön runkoa ennen kuin allekirjoitus on todennettu - muuten kuka tahansa voi lähettää mitä tahansa URL-osoitteeseesi.
import { createHmac, timingSafeEqual } from "node:crypto";
function verifyVolaiSignature(
rawBody: string,
signatureHeader: string | null,
secret: string,
toleranceSecs = 300,
): boolean {
if (!signatureHeader) return false;
const parts = new Map<string, string>();
for (const piece of signatureHeader.split(",")) {
const idx = piece.indexOf("=");
if (idx > 0) parts.set(piece.slice(0, idx), piece.slice(idx + 1));
}
const t = parts.get("t");
const v1 = parts.get("v1");
if (!t || !v1) return false;
const age = Math.abs(Date.now() / 1000 - Number(t));
if (!Number.isFinite(age) || age > toleranceSecs) return false;
const expected = createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected, "utf8");
const b = Buffer.from(v1, "utf8");
return a.length === b.length && timingSafeEqual(a, b);
}
// Next.js route handler - rawBody ON OLTAVA täsmälleen se, mikä tuli langan yli (request.text()), ei JSON.parse ja takaisin merkkijonoksi.
export async function POST(request: Request) {
const rawBody = await request.text();
const valid = verifyVolaiSignature(
rawBody,
request.headers.get("volai-signature"),
process.env.VOLAI_WEBHOOK_SECRET!,
);
if (!valid) return new Response("invalid signature", { status: 401 });
const event = JSON.parse(rawBody);
// ... käsittely taustalla, ks. Vinkkejä alla
void event;
return new Response("ok", { status: 200 });
}import hashlib
import hmac
import time
from flask import Flask, request
app = Flask(__name__)
WEBHOOK_SECRET = "whsec_..."
def verify_volai_signature(raw_body, signature_header, secret, tolerance_secs=300):
if not signature_header:
return False
parts = {}
for piece in signature_header.split(","):
if "=" in piece:
key, value = piece.split("=", 1)
parts[key] = value
t = parts.get("t")
v1 = parts.get("v1")
if not t or not v1:
return False
if abs(time.time() - float(t)) > tolerance_secs:
return False
payload = f"{t}.{raw_body}".encode("utf-8")
expected = hmac.new(secret.encode("utf-8"), payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
@app.route("/webhooks/volai", methods=["POST"])
def volai_webhook():
raw_body = request.get_data(as_text=True)
signature = request.headers.get("Volai-Signature", "")
if not verify_volai_signature(raw_body, signature, WEBHOOK_SECRET):
return "invalid signature", 401
event = request.get_json()
# ... käsittely taustalla, ks. Vinkkejä alla
del event
return "ok", 200Omat otsakkeet
Jos kohde ottaa vastaan vain tunnistautuneita pyyntöjä (esimerkiksi Cursorin automaatio tai oma API yhdyskäytävän takana), lisää avain omaksi otsakkeeksi. Se lähetetään jokaisen toimituksen ja testitapahtuman mukana, esimerkiksi Authorization: Bearer <avain>. Se asetetaan PUT /v1/webhook -pyynnön kentällä headers, MCP-työkalulla set_webhook tai portaalissa kohdassa Yhteydet ja API osiossa Webhookit.
curl -X PUT https://volai.cz/v1/webhook \
-H "Authorization: Bearer $VOLAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://api.example.com/hooks/volai", "events": ["message.received", "call.completed", "call.missed"], "headers": {"Authorization": "Bearer YOUR_TARGET_KEY"}}'- Enintään 5 otsaketta, kunkin arvo 1-1000 merkkiä, vain tulostettavaa ASCII-merkistöä (ei diakriittisiä merkkejä). Nimet eivät erottele kirjainkokoa eikä niitä saa toistaa.
host,content-type,content-length,volai-signatureja hop-by-hop-otsakkeet toimitus asettaa itse, niitä ei voi antaa. - Arvot ovat salaisuuksia:
GET /v1/webhookpalauttaa ne vain lyhennettyinä (Bear***). Jos tällainen peitetty arvo lähetetään takaisin, tallennettu arvo säilyy. - Jos
headersjätetään pois, tallennetut otsakkeet säilyvät,{}poistaa ne. Kun URL vaihdetaan toiseen osoitteeseen (toinen verkkotunnus, skeema tai portti, myös ylimääräinenwww.), tallennetut otsakkeet hylätään ja arvot annetaan uudelleen kokonaan: avainta ei lähetetä vieraaseen osoitteeseen. Jos silloin lähetetään arvon sijaan peitetty arvo, palautuu virheinvalid_webhook_headers(400), samoin kuin kielletystä tai virheellisestä otsakkeesta. - Kun toimitus ohjataan toiseen osoitteeseen, omia otsakkeita ei lähetetä, mutta allekirjoitus
Volai-Signaturelähetetään. Myös ohjaus osoitteestaexample.comosoitteeseenwww.example.comon eri osoite, joten anna webhookissa heti lopullinen kohdeosoite.
Allekirjoitus Volai-Signature lähetetään edelleen omien otsakkeiden rinnalla. Otsake päästää pyynnön sisään, allekirjoitus osoittaa, että sen todella lähetti volai.
Uudelleenyritykset virhetilanteessa
Jos päätepisteesi ei vastaa onnistumistilalla (2xx), volai yrittää vielä kaksi kertaa - yhteensä siis 3 yritystä, joiden välissä on 3 sekunnin tauko. Puhelutapahtumille (`call.completed`, `call.failed`, `call.no_answer`, `call.missed`) ja tapahtumalle `message.received` toimitus ei pääty tähän: jos kaikki kolme yritystä epäonnistuvat, tapahtuma jää jonoon ja toimitusta toistetaan vielä muutaman kerran seuraavien minuuttien aikana, enintään 5 kierrosta. Siksi bodyssa on `event_id` - sen avulla toimitus suodatetaan pois kaksoiskappaleena, jos se poikkeuksellisesti tulisi useita kertoja; toistettu toimitus sisältää täsmälleen saman bodyn kuin ensimmäinen (lähetetty vain muutaman minuutin myöhemmin). Tapahtumalla `message.sent` ei ole jonoa: 3 epäonnistuneen yrityksen jälkeen se kirjataan lokiin eikä lähetetä uudelleen.
Poikkeus on alla oleva testitapahtuma - se lähetetään vain kerran, ilman uudelleenyrityksiä, jotta vastaus tulee heti.
Webhook ei ole ainoa totuuden lähde
Webhook sisältää vain otteen - kaikesta, millä todella on merkitystä (laskutus, auditointi, viestin teksti), kannattaa hakea koko tietue myös REST API:sta: GET /v1/calls/{id} ja GET /v1/messages/{id}, milloin tahansa.
Testitapahtuma
Ennen kuin odotat ensimmäistä oikeaa puhelua, varmista toimitus heti - POST /v1/webhook/test (ks. REST API) lähettää URL-osoitteeseesi yhden esimerkkitapahtuman webhook.test RIIPPUMATTA siitä, mitkä events on valittu PUT /v1/webhook -pyynnössä - testataan itse URL-osoitteen ja allekirjoituksen toimitettavuutta, ei tiettyjen tapahtumien tilausta. Enintään 10 yritystä tunnissa. Testi lähettää vain webhook.test, ei muita tapahtumia: tapahtuman message.received muodon voi kokeilla vasta oikealla tekstiviestillä tuotteeseesi matkapuhelinnumero tai numero puheluille ja tekstiviesteille (esimerkki yllä).
Toimitusten yhteenveto
Viimeiset 50 toimitusta (onnistuneet, epäonnistuneet ja testitoimitukset) näkyvät pyynnöllä GET /v1/webhook/deliveries (ks. REST API), tai suoraan portaalissa webhook-lomakkeen alla. Sama ote on myös pyynnössä GET /v1/webhook kentässä recentDeliveries.
Vinkkejä
- Vastaa 200 mahdollisimman nopeasti - allekirjoituksen todennus ja tunnisteen tallennus ehditään tehdä heti, raskas työ (sähköposti, uudelleenlaskennat, kutsut muihin API-rajapintoihin) siirretään taustalle.
- Päätepisteen on oltava julkisesti saatavilla HTTPS:n yli -
localhostja itse allekirjoitetut varmenteet eivät toimi. - Käytä
data.id-kenttää (puhelun tai viestin tunniste) kaksoiskappaleiden suodattamiseen, jos sama tapahtuma sattuisi tulemaan useita kertoja. - Testaa paikallisesti tunnelin (esim. ngrok) kautta ja vaihda väliaikaisesti
PUT /v1/webhook-pyynnön URL sen osoitteeseen.
Liittyvää
MCP-palvelin
Yhdistä Claude Code, Codex CLI, Codex desktop, Cursor ja muut tekoälyeditorit.
REST API
Täydellinen kuvaus jokaisesta päätepisteestä: numerot, puhelut, tekstiviestit, tekstiviestien matkapuhelinnumerot, agentit ja niiden luonnokset, työkalut, tallenteet, webhookit, soittokieltolista, välitys, tili, tehtävät, saldo, asiakirjat, kalenterit ja integraatiot.
Puheagentti
Järjestelmäkehote, työkalut, siirto ihmiselle, tallenteet ja jäsennelty puhelutieto.