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

# InfraAudit webhooks — real-time event callbacks

> InfraAudit can push real-time event notifications to any HTTP endpoint. Learn how webhooks work, how to register one, and the payload envelope structure.

InfraAudit webhooks deliver real-time HTTP POST callbacks to your application when events fire — detected drifts, cost anomalies, compliance violations, completed remediations, and more. Instead of polling the API for changes, your server receives a JSON payload as soon as the event occurs.

## How it works

When an event fires in InfraAudit, the platform:

1. Constructs a JSON payload with a common envelope and event-specific `data` fields.
2. Signs the payload using HMAC-SHA256 with your webhook's secret key.
3. POSTs the payload to your registered endpoint URL.
4. Retries on failure using exponential backoff — up to 3 attempts over 2.5 hours.

## Register a webhook

Create a webhook endpoint via the API to start receiving events:

```bash theme={null}
curl -X POST https://api.infraaudit.dev/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production receiver",
    "url": "https://receiver.example.com/infraudit",
    "events": ["drift.detected", "alert.created"],
    "enabled": true
  }'
```

The response includes a `secret` used to verify payload signatures. Store it securely — it is returned only once.

You can also register webhooks in the web UI under **Settings → Webhooks**.

## Payload envelope

Every webhook delivery uses the same outer envelope:

```json theme={null}
{
  "event": "drift.detected",
  "timestamp": "2024-01-15T14:30:00Z",
  "webhook_id": "wh_abc123",
  "delivery_id": "del_xyz789",
  "data": { }
}
```

<ResponseField name="event" type="string">
  The event type, for example `drift.detected` or `cost.anomaly`.
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of when the event was generated.
</ResponseField>

<ResponseField name="webhook_id" type="string">
  The ID of the webhook subscription that triggered this delivery.
</ResponseField>

<ResponseField name="delivery_id" type="string">
  A unique ID for this delivery attempt. Use this to deduplicate events on your side, since InfraAudit delivers with at-least-once semantics.
</ResponseField>

<ResponseField name="data" type="object">
  Event-specific payload. Contents vary by event type.
</ResponseField>

## Related pages

* [Event types](/api/webhooks/events) — all events you can subscribe to with example payloads
* [Signature verification](/api/webhooks/signing) — how to validate that a delivery came from InfraAudit
* [Retries and delivery](/api/webhooks/retries) — retry schedule and how to handle delivery failures
* [Webhook API reference](/api/reference/webhooks) — API endpoints for managing webhook subscriptions