Webhooks API¶

The Webhooks API allows organizations to configure HTTP endpoints that receive real-time event notifications from the ARX platform. Webhook events are delivered for security-relevant actions including agent deployments, drift detections, policy violations, approval requests, and connector operations.

All endpoints are scoped to the authenticated user's organization via Row-Level Security.

List Webhook Events¶

Returns all available webhook event types that can be subscribed to.

• Method: GET
• Path: /v1/webhooks/events
• Required Role: Any authenticated user

Example¶

curl -X GET "https://api.arxsec.io/v1/webhooks/events" \
  -H "Authorization: Bearer {token}"

Response¶

{
  "events": [
    "agent.deployed",
    "agent.suspended",
    "agent.rolled_back",
    "connector.called",
    "policy.violated",
    "approval.requested",
    "approval.reviewed",
    "drift.detected",
    "compliance.generated",
    "secret.rotated"
  ]
}

Use the wildcard * when creating a webhook to subscribe to all event types.

List Webhooks¶

Retrieves all configured webhook endpoints for the organization.

• Method: GET
• Path: /v1/webhooks
• Required Role: Any authenticated user

Example¶

curl -X GET "https://api.arxsec.io/v1/webhooks" \
  -H "Authorization: Bearer {token}"

Response¶

{
  "webhooks": [
    {
      "id": "wh-uuid",
      "url": "https://hooks.example.com/arx-events",
      "event_types": ["drift.detected", "agent.suspended"],
      "active": true,
      "created_at": "2026-03-20T09:00:00Z"
    }
  ],
  "total": 1
}

Create Webhook¶

Creates a new webhook endpoint. Returns the signing secret, which is shown only once at creation time. Store the signing secret securely -- it is used to verify that incoming webhook payloads originate from ARX.

• Method: POST
• Path: /v1/webhooks
• Required Role: admin

Request Body¶

Example¶

curl -X POST "https://api.arxsec.io/v1/webhooks" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/arx-events",
    "event_types": ["drift.detected", "agent.suspended", "approval.requested"]
  }'

Response¶

{
  "id": "wh-uuid",
  "url": "https://hooks.example.com/arx-events",
  "event_types": ["drift.detected", "agent.suspended", "approval.requested"],
  "active": true,
  "signing_secret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789-_",
  "created_at": "2026-04-10T17:00:00Z"
}

Returns HTTP status 201 Created. Returns 400 if any event types are invalid (use GET /v1/webhooks/events for valid types). The signing_secret is returned only in this response and cannot be retrieved later. The creation is audit-logged.

Verifying Webhook Signatures¶

Each webhook delivery includes a signature header that can be used to verify the payload originated from ARX. Use the signing_secret returned at creation time to compute an HMAC-SHA256 digest of the raw request body and compare it to the signature header value.

Update Webhook¶

Updates a webhook configuration.

• Method: PATCH
• Path: /v1/webhooks/{webhook_id}
• Required Role: admin

Path Parameters¶

Request Body¶

All fields are optional. Only provided fields are updated.

Example¶

curl -X PATCH "https://api.arxsec.io/v1/webhooks/wh-uuid" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "event_types": ["*"],
    "active": true
  }'

Response¶

Returns the updated webhook object. Returns 400 if no fields are provided. Returns 404 if the webhook is not found.

Delete Webhook¶

Deletes a webhook endpoint. Event deliveries to this endpoint stop immediately.

• Method: DELETE
• Path: /v1/webhooks/{webhook_id}
• Required Role: admin

Path Parameters¶

Example¶

curl -X DELETE "https://api.arxsec.io/v1/webhooks/wh-uuid" \
  -H "Authorization: Bearer {token}"

Response¶

Returns HTTP status 204 No Content on success.