REST API endpoints for webhook subscriptions

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.

GET /api/v1/webhooks
Authorization: Bearer <token>

Response

[
  {
    "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.

POST /api/v1/webhooks
Authorization: Bearer <token>
Content-Type: application/json

Request body

name

string

required

A human-readable label for this webhook.

url

string

required

The HTTPS URL of your receiving endpoint.

events

array

required

List of event types to subscribe to. See Webhook events for the full list.

enabled

boolean

default:"true"

Whether this webhook is active.

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

Response `201`

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

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.

GET /webhooks/ — get webhook

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

GET /api/v1/webhooks/{id}
Authorization: Bearer <token>

PUT /webhooks/ — update webhook

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

PUT /api/v1/webhooks/{id}
Authorization: Bearer <token>
Content-Type: application/json

DELETE /webhooks/ — delete webhook

Deletes a webhook. Returns 204 No Content.

DELETE /api/v1/webhooks/{id}
Authorization: Bearer <token>

POST /webhooks//test — send test event

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

POST /api/v1/webhooks/{id}/test
Authorization: Bearer <token>

GET /webhooks//deliveries — list delivery logs

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

GET /api/v1/webhooks/{id}/deliveries
Authorization: Bearer <token>

Query parameters

status

string

Filter by delivery status: success or failed.

page

integer

default:"1"

Page number.

per_page

integer

default:"20"

Results per page.

Overview

Endpoints

Webhooks

Examples

REST API endpoints for webhook subscriptions

GET /webhooks — list webhooks

Response

POST /webhooks — register a webhook

Request body

Response `201`

GET /webhooks/ — get webhook

PUT /webhooks/ — update webhook

DELETE /webhooks/ — delete webhook

POST /webhooks//test — send test event

GET /webhooks//deliveries — list delivery logs

Query parameters

​GET /webhooks — list webhooks

​Response

​POST /webhooks — register a webhook

​Request body

​Response 201

​GET /webhooks/ — get webhook

​PUT /webhooks/ — update webhook

​DELETE /webhooks/ — delete webhook

​POST /webhooks//test — send test event

​GET /webhooks//deliveries — list delivery logs

​Query parameters

GET /webhooks — list webhooks

Response

POST /webhooks — register a webhook

Request body

Response `201`

GET /webhooks/ — get webhook

PUT /webhooks/ — update webhook

DELETE /webhooks/ — delete webhook

POST /webhooks//test — send test event

GET /webhooks//deliveries — list delivery logs

Query parameters