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
| Įvykis | Kada siunčiamas |
|---|---|
meeting.completed | Susitikimas baigtas apdoroti, jo santrauka, užduotys ir sprendimai paruošti. Vieną kartą kiekvienam susitikimui. |
decision.recorded | Po vieną kartą kiekvienam sprendimui susitikime, kuris ką tik baigtas apdoroti. |
action_item.created | Po 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
-
Įsitikinkite, kad jūsų galinis taškas atsako viešu
httpsadresu, numatytuoju arba 8443 prievadu, su serverio vardu, o ne skaitiniu adresu. -
Iškvieskite
POST /hookssu į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 -
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ų su2xxir JSON turiniu, kuriame yra ta pati reikšmė:{"challenge":"…"}. Jei atsakoma ne taip, užsakymas nepavyksta su klaidacallback_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ėsX-VoiceCap-Subscription-Id. -
Išsaugokite atsakyme gautus
idirsecret. Paslaptis prasidedawhsec_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-timestamp | Kada šis bandymas pasirašytas, Unix sekundėmis. |
webhook-signature | Vienas ar keli tarpais atskirti v1, parašai. |
X-VoiceCap-Subscription-Id | Prenumerata, 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
2xxper 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
4xxar 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:
- Pirmą kartą kvieskite su
since, nurodę, nuo kada pradedate, arba besince, kad pradėtumėte po naujausių įvykių. - Išsaugokite kiekvieno atsakymo
nextCursorir kitame kvietime perduokite jį kaipcursor. Sucursorarsinceįvykiai grąžinami seniausi pirmi. - Kol
hasMoreyratrue, 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.