Gareth Wilson Gareth Wilson

Guide to vivenu Webhooks: Features and Best Practices

Published


vivenu is a ticketing platform for event organisers, covering ticket shops, checkout, access control and fan data. Its webhooks report sales, cancellations, ticket changes, entry scans and account changes as they happen, so you can sync orders to a CRM, issue memberships or update attendance in your own systems.

This guide covers vivenu's webhook configurations, the {mode, id, type, data} envelope, verifying x-vivenu-signature with an hmacKey, and the retry and ordering behaviour vivenu documents.

What are vivenu webhooks?

A vivenu webhook configuration belongs to a seller account. It has a listener URL, a map of the event types to send, and an optional hmacKey for signing. One configuration can carry many types. You can create configurations under Developer > Webhooks in the dashboard or with POST /api/webhooks. The seller account needs the Webhooks feature, and you need the Developer or Admin role.

Every request has the same envelope: mode (dev or prod), id (the transmission ID), type and data, which holds the object, such as { transaction } for transaction.complete.

vivenu webhook features

FeatureDetails
Signaturehex HMAC-SHA256
Signature headerx-vivenu-signature
BodyJSON
Event routingBody field type

From vivenu's webhooks documentation:

  • Calls time out after 10 seconds. A 2xx or 3xx response counts as success. vivenu logs the response body but doesn't evaluate it.
  • Other responses are retried up to six more times, with backoff growing from 30 seconds to 2 hours.
  • Delivery is at least once, and calls may arrive out of order.
  • Failed calls can be re-triggered manually from the dashboard.
  • There are no test events, so you test by causing real events in the development environment.
  • Source IPs aren't stable, and vivenu says not to use them for access control.

Events and payloads

Route on the top-level type. vivenu lists 45 types. Some of them:

| Event routing | Body field type |

Others cover tickets (ticket.updated), purchase intents (purchaseIntent.created through purchaseIntent.cancelled), customers, events, background jobs, ticket transfers, scan.created for entry scans, subscriptions and their payments, bundles and products. fund.*, campaign.*, donation.created and pledge.created appear only in the payload's type list, with no description or data model.

vivenu's per-event examples show only the data object, with schema placeholders rather than real values. Capture a real delivery from the development environment before relying on optional fields.

Setting up vivenu webhooks

  1. In the vivenu dashboard, open Developer > Webhooks, or call POST /api/webhooks.
  2. Enter your listener URL, for example https://example.com/webhooks/vivenu.
  3. Select the event types.
  4. Set an hmacKey and store the same value as VIVENU_HMAC_KEY.
  5. Trigger a real event, such as a test purchase, in the development environment.

Set an hmacKey on the vivenu webhook. Without one, deliveries are unsigned and fail verification.

To route through Hookdeck, create a vivenu source with the hmacKey and use its URL as the listener URL. If a configuration has no hmacKey, leave verification off on the source, since there's no signature to check. For local development:

npx hookdeck-cli listen 3000 vivenu --path /webhooks/vivenu

Securing vivenu webhooks

With an hmacKey set, x-vivenu-signature is the hex HMAC-SHA256 of the raw JSON body, keyed with that value. Without one, vivenu sends no signature. Because vivenu's source IPs change, the signature is the only way to authenticate requests.

vivenu accepts plain HTTP listener URLs, and applies strict certificate validation to HTTPS ones. Use HTTPS, since the body carries customer and order data.

Node.js verification

const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-vivenu-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

The handler deduplicates on the transmission id and checks mode, so development events don't reach production data.

const express = require('express');

const app = express();
const EXPECTED_MODE = process.env.VIVENU_MODE || 'prod';

app.post('/webhooks/vivenu', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.VIVENU_HMAC_KEY;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  let event;
  try {
    event = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!event || typeof event !== 'object' || Array.isArray(event)) return res.sendStatus(400);
  if (typeof event.id !== 'string' || typeof event.type !== 'string') return res.sendStatus(400);
  if (event.mode !== EXPECTED_MODE) return res.sendStatus(200);

  const data = event.data && typeof event.data === 'object' ? event.data : {};

  try {
    if (await alreadyHandled(event.id)) return res.sendStatus(200);
    await queue.add('vivenu-event', { id: event.id, type: event.type, data });
    await markHandled(event.id);
  } catch {
    return res.sendStatus(503);
  }
  res.sendStatus(200);
});

Swap in your own job queue for queue, and your own store for alreadyHandled and markHandled.

The vivenu source type in Hookdeck applies this same verification. Hookdeck answers vivenu with 200 and marks a mismatched request as failed verification. No timestamp is signed, and Hookdeck imposes no time window of its own.

Make vivenu webhooks production-ready. Hookdeck Event Gateway accepts each vivenu call within its 10-second timeout and keeps retrying your service after vivenu's six retries have run out.

vivenu webhook limitations and pain points

Retries stop after about two hours of backoff

The Problem: A long outage leaves calls failed, and someone has to re-trigger them.

Why It Happens: vivenu retries up to six more times, with the backoff growing to 2 hours, then stops.

Workarounds:

  • Re-trigger failed calls from the vivenu dashboard after an outage.
  • Reconcile transactions through the API for busy on-sale periods.

How Hookdeck Can Help: Hookdeck stores each call when it arrives and retries your service on your schedule, with bulk replay.

Calls arrive out of order

The Problem: A ticket.updated can arrive before the ticket.created it follows, or an older update after a newer one.

Why It Happens: vivenu doesn't guarantee calls arrive in the order of the events behind them.

Workarounds:

  • Fetch the current object from the API before acting on an update.
  • Handle an update for an object you haven't stored yet, instead of failing.

How Hookdeck Can Help: Hookdeck records when each call arrived, which makes ordering problems easier to trace.

Signing is optional

The Problem: Configurations without an hmacKey send unsigned requests, and IP allowlisting isn't an option.

Why It Happens: hmacKey is optional, and vivenu's source IPs aren't stable.

Workarounds:

  • Set an hmacKey on every configuration.
  • Reject requests without x-vivenu-signature.

How Hookdeck Can Help: Hookdeck's vivenu source records unsigned or mismatched requests as failed verification, so you can spot configurations missing a key.

No test events and placeholder examples

The Problem: You can't send a sample request, and the docs don't show real payloads.

Why It Happens: vivenu documents no synthetic test events, and its examples use schema placeholders.

Workarounds:

  • Make test purchases and changes in the development environment.
  • Save those deliveries as fixtures.

How Hookdeck Can Help: Hookdeck keeps every delivery from your dev account, ready to replay against your code.

Best practices

Check mode

Development and production events share the same envelope. Compare mode with the environment you expect and skip the rest.

Deduplicate on id

Delivery is at least once. Store the transmission id before acting, as in the idempotency guide.

Respond within 10 seconds

Queue the event and answer. Ticket issuing and CRM updates belong in a worker. Our guide to asynchronous webhook processing covers why.

Accept unknown types

New types can appear in the type list before they're documented. Return 200 for types you don't handle.

Conclusion

vivenu sends seller-account events in a {mode, id, type, data} envelope, signed with a hex HMAC-SHA256 in x-vivenu-signature when you set an hmacKey. Set a key on every configuration, deduplicate on id, check mode, and expect calls out of order.

Hookdeck Event Gateway verifies vivenu calls and retries delivery to your systems well beyond vivenu's own retries.

Get started with Hookdeck for free and handle vivenu webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

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