> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infraudit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive InfraAudit Events via Webhooks

> Register an HTTP endpoint, subscribe to event types, verify HMAC-SHA256 signatures, and handle retries for InfraAudit outbound webhook deliveries.

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

<Tabs>
  <Tab title="UI">
    <Steps>
      <Step title="Open webhook settings">
        Go to **Settings → Webhooks** and click **Add webhook**.
      </Step>

      <Step title="Enter the endpoint URL">
        Enter the HTTPS URL of the endpoint that will receive events.
      </Step>

      <Step title="Select event types">
        Choose the event types you want to subscribe to (see the [full event list](#supported-event-types) below).
      </Step>

      <Step title="Save">
        Click **Save**. InfraAudit generates a signing secret for this webhook — copy it now. It's shown only once.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    infraudit webhook create \
      --url https://receiver.example.com/infraudit \
      --events drift.detected,alert.created \
      --name "My Receiver"
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## Event payload format

All webhook deliveries share a common envelope structure:

```json theme={null}
{
  "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](/api/webhooks/events) 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.

<CodeGroup>
  ```go verify.go theme={null}
  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))
  }
  ```

  ```javascript verify.js theme={null}
  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))
  }
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## 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:

```bash theme={null}
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.