Guide to Versive Webhooks: Features and Best Practices
Versive, formerly Mirio, runs user-research interviews moderated by AI. Participants answer a study's questions, and Versive records and transcribes them. Its webhook tells your systems when an interview is finished, so you can pull the transcript into a research repository, notify the study's owner, or start your own analysis.
| Aspect | Value |
|---|---|
| Method | POST, JSON body |
| Signature headers | svix-id, svix-timestamp, svix-signature (Standard Webhooks) |
| Success | Any 2xx, returned only after your service has accepted the event; anything else is retried (no schedule is documented) |
| Delivery | At-least-once; svix-id is stable across retries |
| Challenge | None |
What are Versive webhooks?
Versive has one webhook event, interview.completed, sent to a single destination for your organisation. You can't create that destination yourself: Versive support provisions it, and destination management isn't part of the public v1 REST API. Deliveries are JSON POST requests signed by Svix. The Versive webhook page covers the whole integration.
Versive webhook features
| Feature | Details |
|---|---|
| Configuration | Provisioned by Versive support |
| Scope | One destination per organisation |
| Signature | Standard Webhooks HMAC-SHA256, via Svix |
| Signature header | svix-signature |
| Secret | From Versive support. Format not shown |
| Body | JSON, no event ID |
| Event routing | Body field event_type |
| Retries | "A delivery may be retried". Schedule not documented |
| Source IPs | Not published |
Events and payloads
| Event | Triggered When | Common Use Cases |
|---|---|---|
interview.completed | A participant completes an interview (screened-out interviews are excluded) | Pull the transcript into your research repository, notify a channel, kick off analysis |
The body holds the event type, the interview and the study. Versive's example is abridged:
{
"event_type": "interview.completed",
"interview": {
"id": "interview-uuid",
"status": "closed",
"vid": "participant-facing-id",
"used_fallback_transcription": false
},
"study": {
"id": "study-uuid",
"title": "Onboarding research"
}
}
The docs say the interview can also include transcript, recording, timing and metadata fields, which the example leaves out. Capture a real delivery before you map them.
interview.used_ is true if any recorded answer was transcribed by a fallback model instead of one of Versive's primary models. An attempt that fails and then succeeds on another primary model doesn't set it, re-transcribing later doesn't clear it, and real-time voice interviews always report false.
Setting up Versive webhooks
Versive support sets up webhooks. Ask them for the endpoint's signing secret.
- Email support@getversive.com with your HTTPS URL, for example
https://example.com/webhooks/versive. - Ask for the endpoint's signing secret and store it in
VERSIVE_WEBHOOK_SECRET. Versive calls it "your endpoint secret" without showing its format; Svix secrets begin withwhsec_, so expect that prefix and keep it.
Changing the URL or rotating the secret also goes through support.
Because changes need a support request, it helps to give Versive a Hookdeck URL from the start. Create a source with the Versive type, add the secret, and send support the source URL. You can then change where interviews go without contacting them again. During development, forward the source with the Hookdeck CLI:
npx hookdeck-cli listen 3000 versive --path /webhooks/versive
Securing Versive webhooks
Versive tells you to verify svix-id, svix-timestamp and svix-signature against the raw body before parsing, and points to Svix's guide. Svix signs id.timestamp.body with HMAC-SHA256, keyed with the base64-decoded secret after whsec_, and svix-signature lists one or more v1, entries. This function checks them and also accepts webhook-* names:
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const prefix = headers['svix-id'] ? 'svix' : 'webhook';
const id = headers[`${prefix}-id`];
const timestamp = headers[`${prefix}-timestamp`];
const signature = headers[`${prefix}-signature`];
if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
!/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
const key = decodeBase64(secret.replace(/^whsec_/, ''));
if (!key) return false;
const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
Versive also recommends a Svix library and rejecting stale timestamps. Those libraries allow five minutes. If Hookdeck sits in front, it applies no tolerance and keeps the original svix-timestamp on retries and replays, so a stale-timestamp check in your app would reject real interviews. The function above verifies the signature and nothing more.
The receiver keys on svix-id, as Versive recommends, and hands the interview to a worker:
const express = require('express');
// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
try {
const value = JSON.parse(rawBody.toString('utf8'));
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
// interviewQueue.add(messageId, event) stores the event once and resolves when durable.
function createVersiveReceiver(interviewQueue) {
const app = express();
app.post('/webhooks/versive', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.VERSIVE_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const event = parseJsonObject(req.body);
if (!event) return res.sendStatus(400); // signed, but not a JSON object
if (event.event_type !== 'interview.completed') return res.sendStatus(200); // acknowledge future types
try {
await interviewQueue.add(req.headers['svix-id'] || req.headers['webhook-id'], event);
} catch {
return res.sendStatus(503);
}
return res.sendStatus(200);
});
return app;
}
A Hookdeck Versive source answers 200 even when the signature is wrong, and records the request as failed verification instead of forwarding it.
Make Versive webhooks production-ready. Hookdeck Event Gateway gives Versive one stable URL to deliver to, so you can reroute interviews without a support ticket.
Versive webhook limitations and pain points
No self-serve configuration
The Problem: Changing the endpoint URL or rotating the secret needs a support request.
Why It Happens: Versive provisions webhooks for each organisation, and destination management isn't in the public API.
Workarounds:
- Register a stable URL you control, such as one behind your own gateway, so internal changes don't need Versive.
How Hookdeck Can Help: Give Versive a Hookdeck source URL once, then change destinations and routing yourself.
Retry policy is undocumented
The Problem: You don't know how long an interview event will be retried if your service is down.
Why It Happens: Versive says only that a delivery may be retried. It gives no schedule, count or timeout.
Workarounds:
- Return
2xxonly after storing the event, and check Versive for interviews completed during any outage.
How Hookdeck Can Help: Hookdeck accepts each event immediately and retries your service on a schedule you configure.
The example payload is abridged
The Problem: You can't map transcript or recording fields from the docs.
Why It Happens: Versive's example shows four interview fields and says others, such as transcript, recording, timing and metadata, may be present.
Workarounds:
- Write the handler around
interview.idandstudy.id, and add fields after inspecting a real delivery.
How Hookdeck Can Help: Hookdeck stores each payload, so you can read a full interview event before writing the code that uses it.
Best practices
Treat payloads as research data
Versive warns that the request is sensitive. Log only the fields you need, restrict access to stored transcripts, and don't publish the destination URL.
Flag fallback transcriptions
If transcript accuracy matters, mark interviews where used_ is true for a human check.
Queue the slow work
Versive asks you to respond promptly and queue long processing. Summarising a transcript belongs in a worker, not the request handler. For storing svix-id safely, see the webhook idempotency guide.
Conclusion
Versive's webhook is one event to one destination, signed by Svix. The work is operational, because setup and any change go through Versive support.
Hookdeck Event Gateway gives Versive a fixed endpoint while you control routing and retries. Sign up free.