Webhooks API

Webhooks allow you to receive real-time notifications when events are logged. Perfect for alerting, SIEM integration, or triggering workflows.

How Webhooks Work

1. You configure a webhook endpoint in your dashboard
2. When an event matches your filters, we send a POST request
3. Your endpoint processes the event and returns 200 OK
4. We retry failed deliveries with exponential backoff

Webhook Payload

Each webhook delivery includes the full event data plus delivery metadata:

1{
2  "id": "wh_delivery_123",
3  "event_id": "evt_8f92a3b4c5d6e7f8",
4  "timestamp": "2025-11-28T12:00:00Z",
5  "event": {
6    "id": "evt_8f92a3b4c5d6e7f8",
7    "action": "user.login",
8    "actor_id": "user_123",
9    "actor_type": "user",
10    "timestamp": "2025-11-28T12:00:00Z",
11    "metadata": {
12      "ip_address": "82.10.22.1"
13    },
14    "signature": "sha256:a1b2c3d4..."
15  }
16}

Verifying Webhooks

All webhook deliveries are signed. Verify the signature to ensure the request came from LogVault:

1import hmac
2import hashlib
3
4def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
5    """Verify a LogVault webhook signature."""
6    expected = hmac.new(
7        secret.encode(),
8        payload,
9        hashlib.sha256
10    ).hexdigest()
11
12    return hmac.compare_digest(f"sha256={expected}", signature)
13
14# In your webhook handler
15@app.post("/webhooks/logvault")
16def handle_webhook(request):
17    signature = request.headers.get("X-LogVault-Signature")
18
19    if not verify_webhook(request.body, signature, WEBHOOK_SECRET):
20        return Response(status=401)
21
22    event = request.json["event"]
23    # Process the event...
24
25    return Response(status=200)

Webhook Headers

Filtering Events

Configure filters to only receive webhooks for specific events:

1{
2  "url": "https://your-app.com/webhooks/logvault",
3  "filters": {
4    "actions": ["user.login", "user.logout", "payment.*"],
5    "actor_types": ["user", "admin"]
6  },
7  "enabled": true
8}

Use wildcards (*) to match multiple actions. For example, payment.* matches payment.processed, payment.failed, etc.

Retry Policy

If your endpoint returns a non-2xx status code, we retry with exponential backoff:

After 6 failed attempts, the delivery is marked as failed and you'll receive an email notification.

Best Practices

• Return 200 quickly - Process events asynchronously to avoid timeouts
• Handle duplicates - Use the delivery ID to deduplicate in case of retries
• Verify signatures - Always verify the webhook signature
• Use HTTPS - Webhook endpoints must use HTTPS

Testing Webhooks

Use the "Test" button in your dashboard to send a test webhook to your endpoint. You can also use tools like webhook.site for debugging.