Siirry sisältöön

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). durationSecs ilmoitetaan 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ä, arvolla endReason: "caller_loop" (hinta 0, 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 esimerkin call.no_answer yhteydessä. volain omalla moottorilla tehdyssä puhelussa (versiosta 15. 10. 2026 alkaen) on lisäksi engine-lohko, jossa on protectedUtterances ja protectedUtterancesCount: soitetun osapuolen repliikit tervehdysikkunan aikana, joita moottori ei tarkoituksella vastaanottanut (”Haloo?” tai nimi agentin ensimmäisen lauseen aikana) - niitä ei ole kentässä transcript eikä agentti reagoinut niihin; sama muoto kuin GET /v1/calls/{id}, ElevenLabsin ja vanhemman moottorin puheluissa avain puuttuu.
  • call.failed - puhelu päättyi tilaan failed - 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 on reason (tekninen syy) ja endReason. 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äksi transcript/summary/durationSecs/priceHal, muilla reason-arvoilla nämä neljä kenttää puuttuvat. Tällaisessa puhelussa reason on joko engine_stall tai engine_error (moottorivirhe), tai unfinished, kun moottorin uudelleenkäynnistys tai pysäytys katkaisi puhelun kesken (esimerkiksi uutta versiota julkaistaessa). Tällaisesta puhelusta ei veloiteta (priceHal on 0), siitä ei ole tallennetta ja summary selittää lyhyesti, mitä tapahtui. transcript sisä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). durationSecs on 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 kohdasta kind: "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 on endReason: "capacity", kesto 0 ja hinta 0; 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ä smsNumber on numero, josta viesti lähetettiin; jaetulla lähettäjällä SMSinfo se on null. Toimituskuittaus (deliveryStatus) tuotteesta matkapuhelinnumero lähetetylle tekstiviestille ja myöhempi epäonnistuminen (failed, jolloin saldo palautetaan) eivät laukaise tapahtumaa - hae tila osoitteesta GET /v1/messages/{id}.
  • message.received - viesti saapui tuotteeseesi matkapuhelinnumero tai tuotteeseesi numero puheluille ja tekstiviesteille. Kentässä data on id, from (lähettäjä: puhelinnumero E.164-muodossa tai tekstinimi, esim. ”Google”, enintään 32 merkkiä; jos lähettäjä puuttuu, arvo on unknown), to (numerosi, johon viesti saapui), body, segments ja receivedAt (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 osoitteesta GET /v1/messages?direction=in. Kuoren ts on tapahtuman syntymisaika (sekin millisekunteina, kun taas allekirjoitusotsakkeen t= 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 osoitteesta GET /v1/messages?direction=in, joka säilyttää enintään 1 000 viimeisintä vastaanotettua viestiä tiliä kohden ja pitää ne 90 päivää. Vapautettavassa (tila releasing) tuotteessa numero puheluille ja tekstiviesteille viesti tallennetaan, mutta message.received ei lähde siitä. Tilille, jonka volain ylläpitäjä on keskeyttänyt käsin, message.received ei lähde lainkaan, eikä keskeytyksen aikana vastaanotetuista viesteistä toimiteta sitä jälkikäteen, kun tili palautetaan; nekin löytyvät osoitteesta GET /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

json
{
  "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

json
{
  "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.

json
{
  "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.

json
{
  "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

json
{
  "event": "message.sent",
  "ts": 1756111640000,
  "data": {
    "id": "msg_7c1f9a2e",
    "to": "+420777123456",
    "status": "sent",
    "priceHal": 136,
    "smsNumber": null
  }
}

message.received

json
{
  "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.

typescript
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 });
}
python
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", 200

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

bash
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-signature ja hop-by-hop-otsakkeet toimitus asettaa itse, niitä ei voi antaa.
  • Arvot ovat salaisuuksia: GET /v1/webhook palauttaa ne vain lyhennettyinä (Bear***). Jos tällainen peitetty arvo lähetetään takaisin, tallennettu arvo säilyy.
  • Jos headers jätetään pois, tallennetut otsakkeet säilyvät, {} poistaa ne. Kun URL vaihdetaan toiseen osoitteeseen (toinen verkkotunnus, skeema tai portti, myös ylimääräinen www.), 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 virhe invalid_webhook_headers (400), samoin kuin kielletystä tai virheellisestä otsakkeesta.
  • Kun toimitus ohjataan toiseen osoitteeseen, omia otsakkeita ei lähetetä, mutta allekirjoitus Volai-Signature lähetetään. Myös ohjaus osoitteesta example.com osoitteeseen www.example.com on 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 - localhost ja 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.