Naršyti dokumentaciją
Dokumentacija

Webhook

Gaukite pasirašytą HTTPS užklausą iš VoiceCap, kai susitikimas paruoštas, užfiksuotas sprendimas ar rasta užduotis.

Webhook prenumerata nurodo VoiceCap siųsti pasirašytą POST užklausą į jūsų adresą kiekvieną kartą, kai įvyksta įvykis, užuot jūsų kodui vis klausinėjus. Prenumeratos priklauso jas sukūrusiam API raktui: raktas mato ir pašalina tik savo prenumeratas.

Įvykiai

ĮvykisKada siunčiamas
meeting.completedSusitikimas baigtas apdoroti, jo santrauka, užduotys ir sprendimai paruošti. Vieną kartą kiekvienam susitikimui.
decision.recordedPo vieną kartą kiekvienam sprendimui susitikime, kuris ką tik baigtas apdoroti.
action_item.createdPo vieną kartą kiekvienai užduočiai ką tik apdoroto susitikimo santraukoje. Vėliau ranka pridėtos užduotys nesiunčiamos.

Įvykius gaunate tik apie susitikimus, kuriuos rakto savininkas gali atidaryti. Visi kiekvieno įvykio laukai išvardyti API žinyne.

Užsakymas

  1. Įsitikinkite, kad jūsų galinis taškas atsako viešu https adresu, numatytuoju arba 8443 prievadu, su serverio vardu, o ne skaitiniu adresu.

  2. Iškvieskite POST /hooks su įvykiu, savo adresu ir norimais filtrais:

    curl -X POST -H "Authorization: Bearer $VOICECAP_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"event":"meeting.completed","targetUrl":"https://example.com/voicecap","filters":{"scope":"mine"}}' \
      https://voicecap.ai/api/v1/hooks
    
  3. Prieš pradėdamas prenumeratą VoiceCap gali išsiųsti į jūsų adresą pasirašytą bandomąją užklausą su turiniu {"type":"verification","challenge":"…"}. Atsakykite į ją per 10 sekundžių su 2xx ir JSON turiniu, kuriame yra ta pati reikšmė: {"challenge":"…"}. Jei atsakoma ne taip, užsakymas nepavyksta su klaida callback_verification_failed.

    Atsakykite tik šiuo objektu. Atsakymas, kuris pakartoja visą užklausą arba turi lauką type, nepriimamas. Bandomoji užklausa pasirašyta paslaptimi, kurią užsakymo kvietimas dar tik grąžins, todėl jos parašo patikrinti dar negalite, o užsakant pirmą kartą joje nėra antraštės X-VoiceCap-Subscription-Id.

  4. Išsaugokite atsakyme gautus id ir secret. Paslaptis prasideda whsec_ ir rodoma tik šiame atsakyme.

Užsakius dar kartą su tuo pačiu raktu, įvykiu, adresu ir filtrais, grąžinamas tas pats id su nauja paslaptimi. Kol prenumerata aktyvi, senoji paslaptis galioja dar 24 valandas, todėl galite pereiti prie naujos nepraleidę nė vieno pristatymo.

Norėdami sustabdyti, iškvieskite DELETE /hooks/{id}. Atsakymas visada yra {"deleted": true}, todėl kartoti saugu. GET /hooks pateikia rakto prenumeratas su jų būsena. Jame rodomas tik kiekvieno adreso serveris, niekada visas adresas, todėl prenumeratas atpažinkite pagal id.

Filtrai

Visi trys įvykiai priima tuos pačius filtrus: scope (mine arba all_visible), classification (internal, external arba any), groupId, participantEmail ir participantDomain. action_item.created dar priima assignedToMe. Nenurodytas filtras netaikomas. scope turi numatytąją reikšmę, kuri priklauso nuo jūsų rolės; API žinyne aprašyta, ką atrenka kiekvienas filtras.

Kaip atrodo pristatymas

Kiekvienas pristatymas yra POST užklausa su JSON turiniu:

{
  "eventId": "5b0c3f1e-…",
  "name": "meeting.completed",
  "timestamp": "2026-10-16T11:30:00+03:00",
  "data": { "meetingId": "…", "title": "Savaitės susitikimas", "…": "…" },
  "cursor": null
}

data yra tokio pat pavidalo kaip vienas GET /hooks/sample elementas, todėl savo apdorojimą galite sukurti ir išbandyti su tikrais įvykiais dar prieš užsakydami. Užklausoje yra šios antraštės:

AntraštėReikšmė
webhook-idĮvykio id, toks pat kaip eventId.
webhook-timestampKada šis bandymas pasirašytas, Unix sekundėmis.
webhook-signatureVienas ar keli tarpais atskirti v1, parašai.
X-VoiceCap-Subscription-IdPrenumerata, kuriai priklauso pristatymas.

meeting.completed įvykyje yra susitikimo santrauka ir išvardytos pirmosios 200 užduočių, pirmieji 200 sprendimų, 50 dalyvių, 20 grupių ir 30 pagrindinių temų; ilgi tekstai sutrumpinami. decision.recorded ir action_item.created įvykiuose tekstai sutrumpinami taip pat. Visą susitikimą perskaitysite su GET /meetings/{id}.

timestamp yra laikas, kada išsiųstas tas pristatymo bandymas, rakto savininko laiko zonoje, todėl pakartotinio bandymo laikas vėlesnis nei pirmojo. Įvykiams atskirti naudokite eventId.

Parašo tikrinimas

Pristatymai pasirašomi pagal Standard Webhooks schemą, todėl bet kuri Standard Webhooks biblioteka juos patikrina su jūsų whsec_ paslaptimi. Jei tikrinate patys: paimkite paslapties dalį po whsec_, iškoduokite ją iš base64 ir apskaičiuokite HMAC-SHA256 nuo webhook-id, taško, webhook-timestamp, taško ir neapdoroto užklausos turinio. Užklausa tikra, jei rezultato base64 sutampa su bet kuriuo v1, įrašu antraštėje webhook-signature.

Tikrinkite neapdorotus turinio baitus, prieš išskaidydami JSON. Atmeskite užklausą, kurios laiko žyma senesnė nei kelios minutės.

Kaip atsakyti į pristatymą

  • Atsakykite bet kuriuo 2xx per 10 sekundžių. Atsakymo turinys nepaisomas.
  • 5xx, 408, 429, viršytas laikas ar nepavykęs ryšys bandomas dar kartą: po 1 minutės, 5 minučių, 30 minučių, 2 valandų, 6 valandų ir 12 valandų. Iš viso apie 21 valandą.
  • Kiti 4xx ar peradresavimas dar kartą nebandomi.
  • Atsakykite 410 Gone, kad sustabdytumėte prenumeratą. VoiceCap jai daugiau nieko nesiųs.

Tas pats pristatymas gali ateiti daugiau nei kartą, o pristatymai gali ateiti ne iš eilės. Pasikartojimus atmeskite pagal eventId.

Jei jūsų galinis taškas nuolat nesėkmingas, VoiceCap prenumeratą sustabdo, o GET /hooks ją rodo kaip suspended. Užsakius iš naujo su tais pačiais nustatymais, ji vėl įjungiama: VoiceCap iš naujo patikrina jūsų adresą, kaip naujai prenumeratai, ir nuo tada galioja tik nauja paslaptis.

Kada pristatymai nutrūksta

Prenumerata sustoja visam laikui, kai jos API raktas atšaukiamas, kai rakto savininkas išeina iš organizacijos ar jo paskyra išjungiama, arba kai ją kas nors sustabdo VoiceCap: rakto savininkas skiltyje Settings > Profile arba Owner ar Admin mygtuku Stop all automations skiltyje Settings > Integrations. Užsakius iš naujo VoiceCap sustabdytą prenumeratą, atsakymas yra 409 subscription_stopped.

Pristatymai taip pat pristabdomi, kol organizacijoje išjungti API raktai, kol VoiceCap joje išjungęs automatizacijas, kol organizacija sustabdyta arba kol rakto savininko el. pašto adresas nepatvirtintas. Pristabdymo metu įvykę įvykiai vėliau nepristatomi, kaip ir įvykis susitikimui, ištrintam prieš pristatymą.

Apklausa vietoj prenumeratos

GET /hooks/sample?event=meeting.completed grąžina iki 10 naujausių įvykių, naujausius pirmus, su tais pačiais filtrais kaip užklausos parametrais. Taip pamatysite, ką gautų prenumerata.

Norėdami apklausti vietoj prenumeratos:

  1. Pirmą kartą kvieskite su since, nurodę, nuo kada pradedate, arba be since, kad pradėtumėte po naujausių įvykių.
  2. Išsaugokite kiekvieno atsakymo nextCursor ir kitame kvietime perduokite jį kaip cursor. Su cursor ar since įvykiai grąžinami seniausi pirmi.
  3. Kol hasMore yra true, kvieskite iš karto vėl: laukia daugiau įvykių.

Taip apklausdami nieko nepraleisite, net jei susitikime yra daugiau užduočių nei telpa į vieną puslapį ar daug susitikimų baigiasi vienu metu. Pasikartojimus atmeskite pagal kiekvieno elemento id.

Susiję puslapiai