# 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](https://docs.vivenu.com/api/core/webhooks):

* 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:

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

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

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

### Respond within 10 seconds

Queue the event and answer. Ticket issuing and CRM updates belong in a worker. Our guide to [asynchronous webhook processing](/webhooks/guides/why-implement-asynchronous-processing-webhooks) 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](https://hookdeck.com) verifies vivenu calls and retries delivery to your systems well beyond vivenu's own retries.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle vivenu webhooks reliably in minutes.