On-Premises

Overview

The Hivel Incident API enables submitting incident data to Hivel, allowing for precise calculation of metrics such as CFR (Change Failure Rate) and MTTR (Mean Time to Recovery).

---

Base URL

This is the on-premises deployment of hivel-agent's webhook gateway, running on your own infrastructure. Unlike the cloud version, it does not use app.hivel.ai or app.hivel.in.

http://<client-host>:8113

Port 8113 is fixed, not configurable, open inbound access to it in your firewall/security group before sending events. A public, unauthenticated health check is also available at GET http://<client-host>:8113/insightlyapi/webhook/health, useful for container/orchestration monitoring.

---

Authentication

All requests require an organization API token. Pass this in the request header:

X-API-Token: YOUR_API_KEY Content-Type: application/json

---

Retrieving Your API Key

1. Open your organization's on-prem Hivel instance and navigate to Integrations under Settings.

   
2. Click on Connect on Hivel API Authorization card

   
3. Follow the given steps to start your integration

4. By clicking on Generate your API Key will be generated.

---

Incident Events API

Endpoint

POST http://<client-host>:8113/api/hooks/v1/incident

Request Parameters

Field Name	Type	Description	Example
description	string	A detailed description of the incident (max 255 chars).	Database connection timeout error
severity Required	string	The severity level of the incident (e.g., low, medium, high, critical) (max 255 chars).	high
affected_systems	array	A list of systems affected by the incident.	["database", "backend"]
reported_time Required	string	The date and time when the incident occurred (ISO 8601 format).	2024-08-01T12:34:56Z
reported_by	string	The username or identifier of the person who reported the incident (max 255 chars).	jdoe
resolution_time Required	string	The date and time when the incident was resolved (ISO 8601 format).	2024-08-01T13:34:56Z
provider_id	string	The unique identifier of the incident in your incident management provider (max 255 chars).	incident-123456
repo_url Required	string	The URL of the repository related to the deployment or incident (max 255 chars).	https://github.com/your-repo/project
pr_number Required	string	The Pull Request (PR) identifier associated with the deployment.	44

Request Example

Example

curl --location 'http://<client-host>:8113/api/hooks/v1/incident' \
--header 'X-API-Token: YOUR_API_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
  "description": "Database connection timeout affecting API",
  "severity": "HIGH",
  "affected_systems": ["database", "api-gateway"],
  "reported_time": "2025-09-22T10:30:00Z",
  "reported_by": "[e-mail]",
  "resolution_time": "2025-09-22T11:15:00Z",
  "provider_id": "inc-20250922-1030",
  "repo_url": "https://github.com/hivelai/webhook-logger",
  "pr_number": "71"
}'

Response

200 - Successful

{
  "message": "Success",
  "incident_id": "incident-2024-08-01-12345"
}

• 400 - Bad Request

• 401 - Unauthorized

• 403 - Org inactive

• 500 - Internal Server Error

A request body that fails to parse as valid JSON, or has a field of the wrong type, returns a 400 Bad Request with the specific parse error in error (same shape as the other 400/500 responses on this page - see above).

401 and 403 use a different response shape than 400/500:

{
  "success": false,
  "message": "Organization is inactive",
  "error": "Forbidden"
}

No details, no correlation_id, those only appear on 400/500 responses.

---