Receive InfraAudit Events via Webhooks

InfraAudit sends an HTTP POST request to your registered endpoint whenever a subscribed event fires. Webhooks work for any event InfraAudit generates — drift detections, alerts, compliance violations, job completions, and more. You can register multiple webhook endpoints and subscribe each one to different event types.

Register a webhook endpoint

Open webhook settings

Go to Settings → Webhooks and click Add webhook.

Enter the endpoint URL

Enter the HTTPS URL of the endpoint that will receive events.

Select event types

Choose the event types you want to subscribe to (see the full event list below).

Save

Click Save. InfraAudit generates a signing secret for this webhook — copy it now. It’s shown only once.

infraudit webhook create \
  --url https://receiver.example.com/infraudit \
  --events drift.detected,alert.created \
  --name "My Receiver"

curl -X POST http://localhost:8080/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Receiver",
    "url": "https://receiver.example.com/infraudit",
    "events": ["drift.detected", "alert.created", "compliance.violation"]
  }'

The response includes the webhook secret. Store it securely — InfraAudit shows it only once.

Event payload format

All webhook deliveries share a common envelope structure:

{
  "event": "drift.detected",
  "timestamp": "2024-01-15T10:30:00Z",
  "webhook_id": "wh_abc123",
  "delivery_id": "del_xyz789",
  "data": {
    "...event-specific fields..."
  }
}

The data field contains fields specific to the event type. See the webhook events reference for the complete schema of each event.

Verify signatures

Every delivery includes an X-InfraAudit-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your webhook’s secret. Always verify this signature before processing a delivery.

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
)

func verifySignature(body []byte, secret, signature string) bool {
  mac := hmac.New(sha256.New, []byte(secret))
  mac.Write(body)
  expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
  return hmac.Equal([]byte(expected), []byte(signature))
}

const crypto = require('crypto')

function verifySignature(body, secret, signature) {
  const hmac = crypto.createHmac('sha256', secret)
  hmac.update(body)
  const expected = 'sha256=' + hmac.digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

Always use a constant-time comparison (like hmac.Equal in Go or crypto.timingSafeEqual in Node.js) to prevent timing attacks. Do not use simple string equality.

Retries

If your endpoint returns a non-2xx HTTP status code or the request times out (10-second timeout), InfraAudit retries the delivery with exponential backoff — up to 3 attempts over 30 minutes. After all retries are exhausted, the delivery is marked as failed. Your endpoint should respond with a 2xx status as quickly as possible. If processing takes time, accept the delivery immediately and process it asynchronously.

Supported event types

Event	Triggered when
`drift.detected`	A new drift finding is created
`drift.resolved`	A drift finding is resolved
`alert.created`	A new alert is created
`vulnerability.found`	A new CVE is detected
`compliance.violation`	A compliance control fails during an assessment
`cost.anomaly`	A cost anomaly is detected
`job.completed`	A scheduled job finishes (success or failure)
`remediation.completed`	A remediation action completes

Test a webhook

After registering, send a test ping event to verify your endpoint receives deliveries:

infraudit webhook test <webhook-id>

The test delivery appears in the webhook’s delivery history under Settings → Webhooks.

View delivery history

In Settings → Webhooks, click any registered webhook to see its delivery history. The history shows the last 100 deliveries with the request payload, response status, response body, and delivery timestamp. Use this to debug integration issues.

Get Started

Platform

Integrations

Concepts

Self-Hosting

Resources

Receive InfraAudit Events via Webhooks

Register a webhook endpoint

Event payload format

Verify signatures

Retries

Supported event types

Test a webhook

View delivery history

​Register a webhook endpoint

​Event payload format

​Verify signatures

​Retries

​Supported event types

​Test a webhook

​View delivery history

Register a webhook endpoint

Event payload format

Verify signatures

Retries

Supported event types

Test a webhook

View delivery history