> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/integrations/deployments-and-incidents/incident-api/on-premises.md).

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

| <p><strong>X-API-Token</strong>: YOUR\_API\_KEY<br><strong>Content-Type</strong>: application/json</p> |
| ------------------------------------------------------------------------------------------------------ |

***

## Retrieving Your API Key

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

   <figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FBmr0wKVXridd3vsOMGf0%2FScreenshot%202026-08-18%20at%205.28.40%E2%80%AFPM.png?alt=media&amp;token=bcb84e79-eca3-470e-a077-ac43462fb941" alt="" width="563"><figcaption></figcaption></figure>
2. Click on **Connect** on **Hivel API Authorization card**<br>

   <figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FpZ80VBIdJuv8BsrwZdOI%2Fimage.png?alt=media&amp;token=0869583b-b6f0-4cda-a6b1-bd1ffc53c640" alt=""><figcaption></figcaption></figure>
3. Follow the given steps to start your integration
4. By clicking on **Generate** your API Key will be generated.

<figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FRj7txCE1jkzHG2J822yp%2Fimage%20(98).png?alt=media&amp;token=2759fa06-84bf-4094-879e-8b10ee6d4281" alt="" width="375"><figcaption></figcaption></figure>

***

### Incident Events API

#### Endpoint

<mark style="color:green;">`POST`</mark> `http://<client-host>:8113/api/hooks/v1/incident`

#### **Request Parameters**

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

#### **Request Example**

{% tabs %}
{% tab title="Example" %}
{% code lineNumbers="true" fullWidth="true" %}

```http
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": "alerts@company.com",
  "resolution_time": "2025-09-22T11:15:00Z",
  "provider_id": "inc-20250922-1030",
  "repo_url": "https://github.com/hivelai/webhook-logger",
  "pr_number": "71"
}'
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### Response

{% tabs %}
{% tab title="200 - Successful" %}

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

{% endtab %}
{% endtabs %}

* `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`:

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

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

***