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

# REST API endpoints for webhook subscriptions

> Register outbound webhook endpoints, subscribe to event types, send test deliveries, delete subscriptions, and view delivery history via the InfraAudit API.

Webhook subscriptions let your application receive real-time HTTP callbacks when InfraAudit events fire. Each webhook has a secret used to sign payloads — store it securely when you create the webhook, as it cannot be retrieved later.

Base path: `/api/v1/webhooks`

***

## GET /webhooks — list webhooks

Returns all registered webhook subscriptions.

```http theme={null}
GET /api/v1/webhooks
Authorization: Bearer <token>
```

### Response

```json theme={null}
[
  {
    "id": "wh_abc123",
    "name": "Production receiver",
    "url": "https://receiver.example.com/infraudit",
    "events": ["drift.detected", "alert.created"],
    "enabled": true,
    "created_at": "2024-01-10T10:00:00Z",
    "last_delivery_status": "success",
    "last_delivery_at": "2024-01-15T14:35:00Z"
  }
]
```

***

## POST /webhooks — register a webhook

Registers a new webhook endpoint. The `secret` signing key is returned only in this response.

```http theme={null}
POST /api/v1/webhooks
Authorization: Bearer <token>
Content-Type: application/json
```

### Request body

<ParamField body="name" type="string" required>
  A human-readable label for this webhook.
</ParamField>

<ParamField body="url" type="string" required>
  The HTTPS URL of your receiving endpoint.
</ParamField>

<ParamField body="events" type="array" required>
  List of event types to subscribe to. See [Webhook events](/api/webhooks/events) for the full list.
</ParamField>

<ParamField body="enabled" type="boolean" default="true">
  Whether this webhook is active.
</ParamField>

```json theme={null}
{
  "name": "Production receiver",
  "url": "https://receiver.example.com/infraudit",
  "events": ["drift.detected", "alert.created", "vulnerability.found"],
  "enabled": true
}
```

### Response `201`

```json theme={null}
{
  "id": "wh_abc123",
  "name": "Production receiver",
  "url": "https://receiver.example.com/infraudit",
  "events": ["drift.detected", "alert.created", "vulnerability.found"],
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx"
}
```

<Warning>
  The `secret` value is returned only at creation time. Store it in your application's secrets manager immediately. It cannot be retrieved after this response.
</Warning>

***

## GET /webhooks/{id} — get webhook

Returns details for a single webhook. The `secret` field is not included.

```http theme={null}
GET /api/v1/webhooks/{id}
Authorization: Bearer <token>
```

***

## PUT /webhooks/{id} — update webhook

Updates a webhook's name, URL, event subscriptions, or enabled state.

```http theme={null}
PUT /api/v1/webhooks/{id}
Authorization: Bearer <token>
Content-Type: application/json
```

***

## DELETE /webhooks/{id} — delete webhook

Deletes a webhook. Returns `204 No Content`.

```http theme={null}
DELETE /api/v1/webhooks/{id}
Authorization: Bearer <token>
```

***

## POST /webhooks/{id}/test — send test event

Sends a `ping` event to the webhook endpoint and returns the delivery result.

```http theme={null}
POST /api/v1/webhooks/{id}/test
Authorization: Bearer <token>
```

***

## GET /webhooks/{id}/deliveries — list delivery logs

Returns the last 100 delivery attempts with request and response details.

```http theme={null}
GET /api/v1/webhooks/{id}/deliveries
Authorization: Bearer <token>
```

### Query parameters

<ParamField query="status" type="string">
  Filter by delivery status: `success` or `failed`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField query="per_page" type="integer" default="20">
  Results per page.
</ParamField>