Guide to vivenu Webhooks: Features and Best Practices
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
| Feature | Details |
|---|---|
| Signature | hex HMAC-SHA256 |
| Signature header | x-vivenu-signature |
| Body | JSON |
| Event routing | Body field type |
From vivenu's webhooks documentation:
- Calls time out after 10 seconds. A
2xxor3xxresponse 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
- In the vivenu dashboard, open Developer > Webhooks, or call
POST /api/webhooks. - Enter your listener URL, for example
https://example.com/webhooks/vivenu. - Select the event types.
- Set an
hmacKeyand store the same value asVIVENU_HMAC_KEY. - 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
hmacKeyon 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.