Webhooks
Get a signed HTTPS request from VoiceCap when a meeting is ready, a decision is recorded or an action item is found.
A webhook subscription tells VoiceCap to send a signed POST to your URL each time an event
happens, instead of your code asking over and over. Subscriptions belong to the API key that
created them: a key lists and removes only its own.
Events
| Event | Sent when |
|---|---|
meeting.completed | A meeting finished processing and its summary, action items and decisions are ready. Once per meeting. |
decision.recorded | Once for each decision in a meeting that just finished processing. |
action_item.created | Once for each action item in the summary of a meeting that just finished processing. Items added by hand later aren't sent. |
You only get events for meetings the key owner can open. Every field of every event is in the API reference.
Subscribing
-
Make sure your endpoint answers on a public
httpsURL, on the default port or 8443, with a hostname rather than a numeric address. -
Call
POST /hookswith the event, your URL and any filters: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 -
Before the subscription starts, VoiceCap may send your URL a signed test request with the body
{"type":"verification","challenge":"…"}. Answer it within 10 seconds with a2xxand a JSON body that holds the same value:{"challenge":"…"}. If it doesn't, the subscribe call fails withcallback_verification_failed.Answer with that object only. A reply that repeats the whole request, or that has a
typefield, fails. The test request is signed with the secret the subscribe call is about to return, so you can't check its signature yet, and the first time you subscribe it has noX-VoiceCap-Subscription-Idheader. -
Keep the
idand thesecretfrom the response. The secret starts withwhsec_and is only shown in this response.
Subscribing again with the same key, event, URL and filters returns the same id with a new
secret. While the subscription is active, the old secret keeps working for 24 hours, so you can
switch over without missing a delivery.
To stop, call DELETE /hooks/{id}. It always answers {"deleted": true}, so it's safe to repeat.
GET /hooks lists the key's subscriptions with their status. It shows the host of each URL, never
the full URL, so match subscriptions on their id.
Filters
All three events take the same filters: scope (mine or all_visible), classification
(internal, external or any), groupId, participantEmail and participantDomain.
action_item.created also takes assignedToMe. Leave a filter out to skip it. scope has a default that depends on your role; the
API reference says what each filter matches.
What a delivery looks like
Each delivery is a POST with a JSON body:
{
"eventId": "5b0c3f1e-…",
"name": "meeting.completed",
"timestamp": "2026-10-16T11:30:00+03:00",
"data": { "meetingId": "…", "title": "Weekly sync", "…": "…" },
"cursor": null
}
data has the same shape as one item from GET /hooks/sample, so you can build and test your
handler against real events before subscribing. The request carries these headers:
| Header | Value |
|---|---|
webhook-id | The event id, the same as eventId. |
webhook-timestamp | When this attempt was signed, in Unix seconds. |
webhook-signature | One or more space-separated v1, signatures. |
X-VoiceCap-Subscription-Id | The subscription the delivery belongs to. |
A meeting.completed event carries the meeting's summary and lists its first 200 action items,
first 200 decisions, 50 participants, 20 groups and 30 key topics; long text fields are shortened.
Text in decision.recorded and action_item.created events is shortened the same way. Read the
meeting with GET /meetings/{id} for everything.
timestamp is when that delivery attempt was sent, in the key owner's time zone, so a retry carries
a later time than the first attempt. Use eventId to tell events apart.
Verifying the signature
Deliveries are signed with the Standard Webhooks scheme, so
any Standard Webhooks library verifies them with your whsec_ secret. To do it yourself: take the
part of the secret after whsec_, base64-decode it, and compute an HMAC-SHA256 over
webhook-id, a period, webhook-timestamp, a period and the raw request body. The request is
genuine if the base64 of the result matches any v1, entry in webhook-signature.
Verify against the raw body bytes, before parsing the JSON. Reject a request whose timestamp is more than a few minutes old.
Answering a delivery
- Answer with any
2xxwithin 10 seconds. The response body is ignored. - A
5xx,408,429, a timeout or a connection failure is tried again: after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. That's about 21 hours in all. - Any other
4xx, or a redirect, is not tried again. - Answer
410 Goneto stop the subscription. VoiceCap sends it nothing more.
A delivery can arrive more than once, and deliveries can arrive out of order. Use eventId to drop
the duplicates.
If your endpoint keeps failing, VoiceCap suspends the subscription and GET /hooks shows it as
suspended. Subscribing again with the same settings turns it back on: VoiceCap checks your URL
again, as for a new subscription, and only the new secret works from then on.
When deliveries stop
A subscription stops for good when its API key is revoked, when the key owner leaves the
organization or their account is deactivated, or when someone stops it in VoiceCap: the key owner
under Settings > Profile, or an Owner or Admin with Stop all automations under
Settings > Integrations. Subscribing again to one stopped in VoiceCap answers
409 subscription_stopped.
Deliveries also pause while API keys are turned off for the organization, while VoiceCap has automations turned off for it, while the organization is suspended, or while the key owner's email address isn't verified. Events that happen during a pause aren't delivered later, and neither is an event for a meeting deleted before its delivery.
Polling instead
GET /hooks/sample?event=meeting.completed returns up to 10 recent events, newest first, with the
same filters as query parameters. Use it to see what a subscription would receive.
To poll instead of subscribing:
- Make the first call with
sinceset to when you start, or with nosinceto begin after the newest events. - Keep the
nextCursorfrom each response and pass it ascursoron the next call. With acursororsince, events come oldest first. - While
hasMoreistrue, call again right away: more events are waiting.
Polling this way misses nothing, even a meeting with more action items than one page holds or many
meetings finishing at once. Deduplicate on each item's id.