Real-time

Webhooks

Receive instant push notifications when content is published. Perfect for Zapier, Make.com, or your own serverless listener.

How Webhooks Work

When content is marked as published in VisualRef, we immediately POST a JSON payload to your configured endpoint. This is ideal for:

Zapier/Make.com

Trigger automations on publish

Serverless Functions

AWS Lambda, Vercel, etc.

Custom CMS

Push to your own platform

Authentication (Optional)

You can optionally define a Secret Token in your integration settings. If declared, VisualRef will bind that token onto every outgoing request header.

Content-Type: application/json
X-Webhook-Secret: <your_secret_token_here>

Event Payload

When content is triggered to distribute, VisualRef pushes the following flat schema:

{
  "title": "Your Blog Post Title",
  "bodyMarkdown": "# Your Blog Post Title\n\n...",
  "htmlContent": "<h1>Your Blog Post Title</h1>...",
  "tags": ["AI", "Tech"],
  "published": true,
  "coverImageUrl": "https://img.host.com/cover.png"
}

Note: The published field is always true for webhook events since they only fire on published content.

Node/Express Listener Example

Here's a minimal Express server that listens for webhook events and validates the secret token:

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

const MY_SECRET = "super-secret-string";

app.post('/visualref/webhook', (req, res) => {
  const providedSecret = req.headers['x-webhook-secret'];
  if (providedSecret !== MY_SECRET) {
    return res.status(401).json({ error: "Unauthorized request" });
  }

  const { title, htmlContent } = req.body;
  console.log(`Pushed article: ${title}`);
  
  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Webhook listener established'));

Retry Logic

If your endpoint fails to respond (non-2xx status), VisualRef will retry up to 3 times with exponential backoff over 1 hour. After all retries are exhausted, the event is logged but not delivered.