LogVaultLogVault
Docs

Webhooks Setup Guide

Learn how to set up webhooks to receive real-time notifications when audit events are logged.

Overview

Webhooks are HTTP callbacks that notify your application when events occur. Common use cases include:

  • Sending alerts for suspicious activity
  • Syncing events to your SIEM
  • Triggering automated workflows
  • Building real-time dashboards

Step 1: Create Your Endpoint

First, create an HTTPS endpoint that can receive POST requests. Here's a simple example with Express.js:

JavaScript
1const express = require('express');
2const crypto = require('crypto');
3
4const app = express();
5app.use(express.json());
6
7const WEBHOOK_SECRET = process.env.LOGVAULT_WEBHOOK_SECRET;
8
9app.post('/webhooks/logvault', (req, res) => {
10  // 1. Verify the signature
11  const signature = req.headers['x-logvault-signature'];
12  const payload = JSON.stringify(req.body);
13
14  const expectedSig = 'sha256=' + crypto
15    .createHmac('sha256', WEBHOOK_SECRET)
16    .update(payload)
17    .digest('hex');
18
19  if (signature !== expectedSig) {
20    return res.status(401).send('Invalid signature');
21  }
22
23  // 2. Process the event
24  const { event } = req.body;
25  console.log('Received event:', event.action, event.actor_id);
26
27  // 3. Return 200 quickly
28  res.status(200).send('OK');
29
30  // 4. Do async processing after responding
31  processEventAsync(event);
32});
33
34app.listen(3000);

Step 2: Configure in Dashboard

  1. Go to Settings → Webhooks in your LogVault dashboard
  2. Click Add Webhook
  3. Enter your endpoint URL (must be HTTPS)
  4. Copy the Webhook Secret - you'll need this to verify signatures
  5. Configure filters (optional)
  6. Click Save

Step 3: Configure Filters

You probably don't want to receive every single event. Use filters to only get what you need:

JSON
1{
2  "filters": {
3    "actions": [
4      "user.login_failed",
5      "payment.*",
6      "admin.*"
7    ],
8    "actor_types": ["user", "admin"]
9  }
10}

Filter Examples

Use CaseFilter
Security alerts["*.failed", "*.deleted", "admin.*"]
Payment events["payment.*", "subscription.*"]
User activity["user.*"]

Step 4: Test Your Webhook

Use the Test button in the dashboard to send a test event to your endpoint. The test payload looks like:

JSON
1{
2  "id": "wh_delivery_test_123",
3  "event_id": "evt_test_123",
4  "timestamp": "2025-11-28T12:00:00Z",
5  "test": true,
6  "event": {
7    "id": "evt_test_123",
8    "action": "test.webhook",
9    "actor_id": "system",
10    "timestamp": "2025-11-28T12:00:00Z"
11  }
12}

Handling Failures

If your endpoint returns an error, LogVault retries with exponential backoff. To avoid failures:

  • Return 200 immediately - Don't do heavy processing before responding
  • Use a queue - Push events to a message queue for async processing
  • Handle duplicates - Use the delivery ID to deduplicate
  • Set up monitoring - Alert on webhook failures

Example: Slack Alert

Here's a complete example that sends Slack alerts for failed login attempts:

JavaScript
1const express = require('express');
2const crypto = require('crypto');
3
4const app = express();
5app.use(express.json());
6
7const WEBHOOK_SECRET = process.env.LOGVAULT_WEBHOOK_SECRET;
8const SLACK_WEBHOOK_URL = process.env.SLACK_WEBHOOK_URL;
9
10function verifySignature(payload, signature) {
11  const expected = 'sha256=' + crypto
12    .createHmac('sha256', WEBHOOK_SECRET)
13    .update(payload)
14    .digest('hex');
15  return crypto.timingSafeEqual(
16    Buffer.from(signature),
17    Buffer.from(expected)
18  );
19}
20
21async function sendSlackAlert(event) {
22  await fetch(SLACK_WEBHOOK_URL, {
23    method: 'POST',
24    headers: { 'Content-Type': 'application/json' },
25    body: JSON.stringify({
26      text: `🚨 Failed login attempt\n*User:* ${event.actor_id}\n*IP:* ${event.metadata?.ip_address || 'Unknown'}\n*Time:* ${event.timestamp}`
27    })
28  });
29}
30
31app.post('/webhooks/logvault', async (req, res) => {
32  const signature = req.headers['x-logvault-signature'];
33  const payload = JSON.stringify(req.body);
34
35  if (!verifySignature(payload, signature)) {
36    return res.status(401).send('Invalid signature');
37  }
38
39  res.status(200).send('OK');
40
41  const { event } = req.body;
42  if (event.action === 'user.login_failed') {
43    await sendSlackAlert(event);
44  }
45});
46
47app.listen(3000);

Next Steps