Webhooks

Set up webhooks to receive real-time notifications when events happen in your Waldium site. Automate workflows, integrate with external services, and build custom applications that respond to your content changes.

Setting up webhooks

To set up a new webhook, you need a URL endpoint that can receive HTTP POST requests. Configure webhooks from your Waldium dashboard under Settings → Webhooks. Choose the events you want to listen for and provide your endpoint URL.

When events occur in your site, Waldium will send webhook notifications to your endpoint. In the next section, we'll look at how to handle these webhook requests.

Handling webhooks

When your endpoint receives a webhook request from Waldium, check the event field to see what happened. The event type tells you what data to expect in the payload.

{
  "event": "post.published",
  "data": {
    "id": "post-uuid",
    "title": "My Blog Post",
    "slug": "my-blog-post",
    "url": "https://your-site.waldium.app/posts/my-blog-post"
  },
  "timestamp": "2024-01-01T12:00:00.000Z",
  "id": "webhook-event-uuid"
}

In the example above, a post was published, and the payload contains the post details.

Event types

{
  "event": "post.published",
  "data": {
    "id": "post-uuid",
    "title": "My Blog Post",
    "slug": "my-blog-post",
    "description": "Post description",
    "category": "Technology",
    "tags": ["web", "development"],
    "authorId": "author-uuid",
    "publishedAt": "2024-01-01T12:00:00.000Z",
    "url": "https://your-site.waldium.app/posts/my-blog-post"
  },
  "timestamp": "2024-01-01T12:00:00.000Z",
  "id": "webhook-event-uuid"
}

Security

To verify that a webhook was sent by Waldium, check the request signature. Each webhook includes an HMAC-SHA256 signature in the X-Webhook-Signature header. Use your webhook secret to verify the signature matches the request payload.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// In your webhook handler
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  const event = JSON.parse(payload);
  console.log('Received event:', event.event);
  
  res.status(200).send('OK');
});

If your generated signature matches the X-Webhook-Signature header, you can be sure the request came from Waldium. Keep your webhook secret safe and never commit it to version control.