Gareth Wilson Gareth Wilson

Guide to Versive Webhooks: Features and Best Practices

Published


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.

AspectValue
MethodPOST, JSON body
Signature headerssvix-id, svix-timestamp, svix-signature (Standard Webhooks)
SuccessAny 2xx, returned only after your service has accepted the event; anything else is retried (no schedule is documented)
DeliveryAt-least-once; svix-id is stable across retries
ChallengeNone

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

FeatureDetails
ConfigurationProvisioned by Versive support
ScopeOne destination per organisation
SignatureStandard Webhooks HMAC-SHA256, via Svix
Signature headersvix-signature
SecretFrom Versive support. Format not shown
BodyJSON, no event ID
Event routingBody field event_type
Retries"A delivery may be retried". Schedule not documented
Source IPsNot published

Events and payloads

EventTriggered WhenCommon Use Cases
interview.completedA 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_fallback_transcription 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.

  1. Email support@getversive.com with your HTTPS URL, for example https://example.com/webhooks/versive.
  2. 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 with whsec_, 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 2xx only 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.id and study.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_fallback_transcription 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.