Webhooks Overview

Webhooks let your application receive real-time HTTP notifications when events occur in your Vivreal group — such as a collection object being created, an integration connecting, or a site deployment completing.

How Webhooks Work

When an event occurs, Vivreal sends an HTTP POST request to your registered endpoint URL with a JSON payload describing the event. Your server processes the payload and returns a 200 response to acknowledge receipt.

Vivreal Event → HTTP POST → Your Endpoint → 200 OK

If your endpoint does not respond with a 2xx status code, Vivreal retries the delivery according to the retry policy.

Setting Up a Webhook

Create an endpoint

Build an HTTP endpoint in your application that accepts POST requests. The endpoint should parse JSON bodies and return a 200 status on success.

// Express.js example
app.post('/webhooks/vivreal', (req, res) => {
  const event = req.body;
  console.log('Received event:', event.event);

  // Process the event...

  res.status(200).json({ received: true });
});

Register the endpoint in Vivreal

In the Vivreal portal, go to Group Settings and find the Webhooks section. Click Add Endpoint and enter your public URL (must be HTTPS).

Select event types

Choose which events should be sent to this endpoint. You can subscribe to all events or select specific types like collection.object.created or site.deployed.

Copy the signing secret

After creating the webhook, Vivreal generates a signing secret. Copy it and store it securely — you will use it to verify that incoming requests are genuinely from Vivreal.

Signature Verification

Every webhook request includes an x-vivreal-signature header containing an HMAC-SHA256 signature of the request body. Always verify this signature before processing the event.

import crypto from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your handler:
app.post('/webhooks/vivreal', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-vivreal-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  // Process event...
  res.status(200).json({ received: true });
});

Always verify signatures

Without signature verification, anyone could send fake events to your endpoint. Use crypto.timingSafeEqual() to prevent timing attacks during comparison.

Retry Policy

If your endpoint returns a non-2xx status code or times out (30 second limit), Vivreal retries delivery with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed retries, the event is marked as failed. You can view failed deliveries in the webhook settings panel and manually retry them.

Idempotency matters

Your endpoint may receive the same event more than once due to retries. Use the id field in the payload to deduplicate events and ensure your processing logic is idempotent.

Testing Webhooks Locally

During development, your local machine is not publicly accessible. Here are two approaches:

Using a tunnel service

Tools like ngrok create a public URL that tunnels to your local server:

ngrok http 3000
# Gives you: https://abc123.ngrok.io
# Register this URL as your webhook endpoint

Best Practices

Respond quickly — Return 200 immediately, then process the event asynchronously. Long-running processing should happen in a background job.
Store raw payloads — Log the raw JSON payload for debugging, even after processing.
Handle unknown events gracefully — New event types may be added over time. Return 200 for events you do not recognize rather than erroring.
Use HTTPS — Webhook endpoints must use HTTPS to protect payload data in transit.

Next Steps

Event Types — Full list of webhook event types.
Payload Schemas — Detailed payload structures and examples.