# Guide to Versive Webhooks: Features and Best Practices

[Versive](https://getversive.com/), 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](https://docs.getversive.com/api-reference/webhooks) 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:

```json
{
  "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](mailto: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](/docs/cli):

```bash
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:

```javascript
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:

```javascript
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](/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](/docs/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](/docs/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](/webhooks/guides/implement-webhook-idempotency).

## 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](https://hookdeck.com) gives Versive a fixed endpoint while you control routing and retries. [Sign up free](https://dashboard.hookdeck.com/signup).