Set up a simple Express.js server that listens for incoming webhook events:

const express = require("express");
const crypto = require("crypto");

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET; // from Vivreal

function verifySignature(payload, signature) {
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post("/webhooks/vivreal", (req, res) => {
  const signature = req.headers["x-vivreal-signature"];

  if (!signature || !verifySignature(req.body, signature)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { event, data } = req.body;
  console.log(`Received event: ${event}`, data);

  switch (event) {
    case "collection.object.created":
      // Handle new object
      break;
    case "collection.object.updated":
      // Handle update
      break;
    case "collection.object.deleted":
      // Handle deletion
      break;
    default:
      console.log("Unknown event type:", event);
  }

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

app.listen(3001, () => console.log("Webhook receiver on :3001"));

If you are developing locally, use ngrok to create a public URL:

ngrok http 3001

Copy the forwarding URL (e.g. https://abc123.ngrok.io).

In the portal, go to Integrations → Webhooks → + New Webhook. Fill in:

• URL: Your public endpoint (e.g. https://abc123.ngrok.io/webhooks/vivreal)
• Events: Select the events you want to receive (collection.object.created, collection.object.updated, collection.object.deleted)
• Secret: Vivreal generates an HMAC secret. Copy it and set it as WEBHOOK_SECRET in your server environment.

Click Save to activate the webhook.

Create or edit an object in any collection. Your webhook receiver should log the incoming event within a few seconds. The payload structure looks like this:

{
  "event": "collection.object.created",
  "timestamp": "2026-03-15T12:00:00Z",
  "data": {
    "collectionName": "Blog Posts",
    "objectId": "abc123",
    "fields": {
      "title": "New Post",
      "tags": ["announcement"]
    }
  }
}

Vivreal retries failed webhook deliveries up to 3 times with exponential backoff. Your endpoint should:

• Return a 2xx status code within 10 seconds to acknowledge receipt.
• Process heavy work asynchronously (e.g. queue it) rather than blocking the response.
• Log failures for debugging — check the Webhook Delivery section in Integrations for delivery history.