Webhooks

Set up outgoing webhooks to receive real-time notifications when VGuard events occur.

Overview

VGuard Cloud can send HTTP POST requests to your endpoints when specific events occur. Use webhooks to integrate with Slack, Discord, PagerDuty, or any custom system.

Setup

Navigate to Settings > Webhooks in the Cloud dashboard
Click Add Webhook
Enter your endpoint URL (must be HTTPS)
Select the events you want to receive
Copy the signing secret for verification

Supported Events

Event	Fires When
`drift.detected`	Convention drift exceeds your configured threshold
`debt.threshold_crossed`	Debt score crosses a warning or critical threshold
`rule_hit.block`	A rule blocks a tool execution during an AI session
`session.completed`	An AI coding session ends and data is synced

Payload Format

All webhook payloads follow the same envelope:

{
  "event": "rule_hit.block",
  "timestamp": "2026-04-03T14:30:00.000Z",
  "project": {
    "id": "proj_abc123",
    "name": "my-app",
    "slug": "my-app"
  },
  "data": {}
}

`rule_hit.block` Data

{
  "ruleId": "security/branch-protection",
  "severity": "block",
  "filePath": "src/index.ts",
  "tool": "Edit",
  "sessionId": "sess_xyz789"
}

`drift.detected` Data

{
  "score": 0.73,
  "previousScore": 0.85,
  "topDrifts": [
    { "rule": "quality/naming-conventions", "delta": -0.08 },
    { "rule": "quality/import-aliases", "delta": -0.04 }
  ]
}

`debt.threshold_crossed` Data

{
  "debtScore": 42,
  "threshold": 30,
  "level": "critical",
  "topContributors": [
    { "rule": "quality/anti-patterns", "hits": 18 },
    { "rule": "quality/no-console-log", "hits": 12 }
  ]
}

`session.completed` Data

{
  "sessionId": "sess_xyz789",
  "duration": 1823,
  "totalHits": 15,
  "blocks": 2,
  "warnings": 8,
  "info": 5
}

Signature Verification

Every webhook request includes an X-VGuard-Signature header containing an HMAC-SHA256 signature of the request body using your signing secret.

Verify it server-side to ensure the request is authentic:

import { createHmac } from 'node:crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  return signature === expected;
}

Always verify signatures before processing webhook payloads.

Retry Logic

If your endpoint returns a non-2xx status code, VGuard Cloud retries with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours

After 4 failed retries, the delivery is marked as failed. You can view delivery history and retry manually from the webhook detail page in Settings > Webhooks.

Best Practices

Respond quickly: Return a 200 status within 5 seconds. Process the payload asynchronously if needed.
Verify signatures: Always validate the X-VGuard-Signature header.
Handle duplicates: Webhooks may be delivered more than once. Use the timestamp and event data to deduplicate.
Use HTTPS: Webhook endpoints must use HTTPS. HTTP URLs are rejected.