Browse the docs
Documentation

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

EventSent when
meeting.completedA meeting finished processing and its summary, action items and decisions are ready. Once per meeting.
decision.recordedOnce for each decision in a meeting that just finished processing.
action_item.createdOnce 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

  1. Make sure your endpoint answers on a public https URL, on the default port or 8443, with a hostname rather than a numeric address.

  2. Call POST /hooks with 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
    
  3. 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 a 2xx and a JSON body that holds the same value: {"challenge":"…"}. If it doesn't, the subscribe call fails with callback_verification_failed.

    Answer with that object only. A reply that repeats the whole request, or that has a type field, 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 no X-VoiceCap-Subscription-Id header.

  4. Keep the id and the secret from the response. The secret starts with whsec_ 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:

HeaderValue
webhook-idThe event id, the same as eventId.
webhook-timestampWhen this attempt was signed, in Unix seconds.
webhook-signatureOne or more space-separated v1, signatures.
X-VoiceCap-Subscription-IdThe 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 2xx within 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 Gone to 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:

  1. Make the first call with since set to when you start, or with no since to begin after the newest events.
  2. Keep the nextCursor from each response and pass it as cursor on the next call. With a cursor or since, events come oldest first.
  3. While hasMore is true, 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.