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"]
}'
secret. Store it securely — InfraAudit shows it only once.{
"event": "drift.detected",
"timestamp": "2024-01-15T10:30:00Z",
"webhook_id": "wh_abc123",
"delivery_id": "del_xyz789",
"data": {
"...event-specific fields..."
}
}
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))
}
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>
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.