> 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/deployment-api/on-premises.md).

# On-Premises

The Deployment Events API lets you track deployment activity (started and completed) for your organization. These events are used to calculate DORA metrics such as deployment frequency and change failure rate.

#### 1. Base URL <a href="#id-1-base-url" id="id-1-base-url"></a>

Port `8113` is fixed, not configurable. 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`.

<pre data-expandable="true"><code>base url: <a data-footnote-ref href="#user-content-fn-1">http://&#x3C;client-host-or-domain>:8113</a>
</code></pre>

{% hint style="info" %}
On the EC2 instance hosting the service on port **8113**, configure the associated **Security Group** to allow inbound TCP traffic on port **8113** from the IP address of the system making requests to the Deployment API.
{% endhint %}

A public, unauthenticated health check is also available at `GET http://<client-host-or-domain>:8113/insightlyapi/webhook/health`, useful for container/orchestration monitoring.

#### 2. Authentication <a href="#id-2-authentication" id="id-2-authentication"></a>

All API requests require an Organization API Key.

**Headers:**

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

**How to Retrieve Your API Key:**

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

<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 Deployment API card.

<figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2Fr61m7DRU3RaOj7GIzM0t%2Fimage.png?alt=media&amp;token=5f6f1747-7bb6-4dd2-a4b2-4f6fbc824c82" alt="" width="374"><figcaption></figcaption></figure>

3. Follow steps to Generate API key.

<figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FgVQKHE1sREqt7K6sV2jM%2Fimage.png?alt=media&amp;token=50b414f5-f008-4475-88b1-7e16a25c2e4e" alt="" width="375"><figcaption></figcaption></figure>

#### 3. API Overview <a href="#id-3-api-overview" id="id-3-api-overview"></a>

| Model                      | Endpoint                      | Use Case                                                                         |
| -------------------------- | ----------------------------- | -------------------------------------------------------------------------------- |
| v2 – Single Event Workflow | POST /api/hooks/v2/deployment | CI/CD sends one event after finishing, containing both start and end timestamps. |

* v2 emits a single event after finishing your CI/CD job.

{% hint style="info" %}
On-prem processes submitted events on a fixed interval, every 3 hours, rather than the daily batch job cloud uses. If you're checking DORA metrics right after sending a test event, expect up to a 3-hour delay before it appears, not immediate processing.
{% endhint %}

#### 4. Required Fields <a href="#id-4-required-fields" id="id-4-required-fields"></a>

**v2 (Single event: completed)**

{% hint style="info" %}
**Note**: Hivel calculates duration as end\_time - start\_time.
{% endhint %}

| Field          | Required | Notes                                                                                                                                                                                                                                                                                                              |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| deployment\_id | Yes      | Must be unique.                                                                                                                                                                                                                                                                                                    |
| event\_type    | Yes      | Must be "completed".                                                                                                                                                                                                                                                                                               |
| status         | Yes      | "success", "failed", "canceled", "unknown"                                                                                                                                                                                                                                                                         |
| start\_time    | Yes      | Deployment start timestamp.                                                                                                                                                                                                                                                                                        |
| end\_time      | Yes      | Deployment end timestamp.                                                                                                                                                                                                                                                                                          |
| repo\_url      | Yes      | <p>Git repo URL.<br><br>e.g Web URL (or HTML URL): <a href="https://github.com/hivelai/webhook-logger"><code><https://github.com/hivelai/webhook-logger></code></a><br>Git Clone URL: <a href="https://github.com/hivelai/webhook-logger.git"><code><https://github.com/hivelai/webhook-logger.git></code></a></p> |
| environment    | Yes      | production / staging / dev / etc (string value).                                                                                                                                                                                                                                                                   |
| branch         | Yes      | Branch name on which CI/CD is running.                                                                                                                                                                                                                                                                             |
| commit\_hash   | No       | Yes, if available.                                                                                                                                                                                                                                                                                                 |
| pr\_number     | No       | Yes, if available.                                                                                                                                                                                                                                                                                                 |
| pr\_numbers    | No       | Yes, if available.                                                                                                                                                                                                                                                                                                 |
| build\_number  | No       | Optional metadata.                                                                                                                                                                                                                                                                                                 |
| image          | No       | Optional metadata.                                                                                                                                                                                                                                                                                                 |
| logs\_url      | No       | Optional metadata.                                                                                                                                                                                                                                                                                                 |

#### 5. Accepted Timestamp Formats <a href="#id-5-accepted-timestamp-formats" id="id-5-accepted-timestamp-formats"></a>

Hivel accepts all common timestamp formats:

* **ISO / RFC 3339**
  * 2025-11-19T10:20:32Z
  * 2025-11-19T10:20:32.846Z
* **Epoch**
  * Seconds: 1700385632
  * Milliseconds: 1700385632846

#### 6. Status Normalization <a href="#id-6-status-normalization" id="id-6-status-normalization"></a>

Hivel simplifies pipeline status tracking by automatically mapping your custom status strings into four standardized values (`success`, `failed`, `canceled`, `unknown`).

{% hint style="warning" %}
💡 **Key Takeaway**: Just send whatever status your CI/CD reports - Hivel will automatically translate it into the four standard values shown below. If you prefer to handle the translation logic yourself before sending the data, that works too.&#x20;
{% endhint %}

**Mapping Reference**

<table><thead><tr><th width="257.30078125"></th><th></th></tr></thead><tbody><tr><td><strong>Provider</strong></td><td><strong>Status Mapping Logic</strong></td></tr><tr><td>Jenkins</td><td><p>• <code>SUCCESS</code> → <strong>success</strong></p><p>• <code>FAILURE</code>, <code>UNSTABLE</code> → <strong>failed</strong></p><p>• <code>ABORTED</code> → <strong>canceled</strong></p><p>• <code>NOT_BUILT</code> → <strong>unknown</strong></p></td></tr><tr><td>GitHub Actions</td><td><p>• <code>success</code> → <strong>success</strong></p><p>• <code>failure</code>, <code>timed_out</code> → <strong>failed</strong></p><p>• <code>canceled</code> → <strong>canceled</strong></p><p>• <code>neutral</code>, <code>skipped</code>, <code>stale</code>, <code>action_required</code> (or other non-terminal statuses) → <strong>unknown</strong></p></td></tr><tr><td>GitLab CI</td><td><p>• <code>success</code> → <strong>success</strong></p><p>• <code>failed</code> → <strong>failed</strong></p><p>• <code>canceled</code> → <strong>canceled</strong></p><p>• <code>manual</code>, <code>skipped</code>, <code>pending</code>, <code>running</code> → <strong>unknown</strong></p></td></tr><tr><td>CircleCI</td><td><p>• <code>success</code> → <strong>success</strong></p><p>• <code>failed</code>, <code>timedout</code>, <code>infrastructure_fail</code> → <strong>failed</strong></p><p>• <code>canceled</code> → <strong>canceled</strong></p><p>• <code>not_run</code>, <code>on_hold</code>, <code>queued</code>, <code>running</code> → <strong>unknown</strong></p></td></tr><tr><td>Argo Workflows</td><td><p>• <code>Succeeded</code> → <strong>success</strong></p><p>• <code>Failed</code>, <code>Error</code> → <strong>failed</strong></p><p>• <code>Skipped</code>, <code>Omitted</code> (or non-terminal like Pending, Running) → <strong>unknown</strong></p></td></tr><tr><td>Azure DevOps</td><td><p>• <code>succeeded</code> → <strong>success</strong></p><p>• <code>failed</code> → <strong>failed</strong></p><p>• <code>canceled</code> → <strong>canceled</strong></p><p>• <code>partiallySucceeded</code>, <code>succeededWithIssues</code> → <strong>unknown</strong></p></td></tr><tr><td>ArgoCD</td><td><p>• <code>operationState.phase</code> = Succeeded, <code>health.status</code> = Healthy → <strong>success</strong></p><p>• <code>phase</code> = Failed or Error, or <code>health</code> = Degraded → <strong>failed</strong></p><p>• Running / Progressing / Missing / Suspended → <strong>unknown</strong></p></td></tr><tr><td>Any other provider</td><td>• Default → <strong>unknown</strong></td></tr></tbody></table>

#### 7. Common CI/CD Field Mapping <a href="#id-7-common-cicd-field-mapping" id="id-7-common-cicd-field-mapping"></a>

Use the following variables to populate the Deployment Events API payload in your CI/CD workflow.

Values may differ depending on your tool version, runner type, or plugin, so always verify using your platform's official documentation.

| Field          | GitHub Actions                                | GitLab CI              | Jenkins                         | Azure DevOps                 | ArgoCD                                                                               |
| -------------- | --------------------------------------------- | ---------------------- | ------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------ |
| repo\_url      | `${{ github.repository }}`                    | `$CI_PROJECT_URL`      | `$GIT_URL`                      | `$(Build.Repository.Uri)`    | `spec.source.repoURL`                                                                |
| commit\_hash   | `${{ github.sha }}`                           | `$CI_COMMIT_SHA`       | `$GIT_COMMIT`                   | `$(Build.SourceVersion)`     | `status.sync.revision`                                                               |
| environment    | `${{ github.environment }}`                   | `$CI_ENVIRONMENT_NAME` | `$ENVIRONMENT`                  | `$(Release.EnvironmentName)` | You define this, typically `spec.destination.name` or `spec.destination.namespace`   |
| start\_time    | Step output (e.g. `steps.start.outputs.time`) | `$CI_JOB_STARTED_AT`   | `$BUILD_ID` / plugin timestamps | `$(Build.StartTime)`         | `status.operationState.startedAt`                                                    |
| end\_time      | Workflow end timestamp                        | `$CI_JOB_FINISHED_AT`  | Timestamp + duration            | `$(Build.FinishTime)`        | `status.operationState.finishedAt`                                                   |
| deployment\_id | -                                             | -                      | -                               | -                            | `metadata.name` or `metadata.uid`                                                    |
| status         | -                                             | -                      | -                               | -                            | Computed from `status.operationState.phase` + `status.health.status`                 |
| event\_type    | -                                             | -                      | -                               | -                            | completed                                                                            |
| logs\_url      | -                                             | -                      | -                               | -                            | Optional: Argo CD UI link, e.g. `https://argocd.example.com/applications/<app-name>` |

{% hint style="warning" %}
**⚠️ Important Notes**

* **Platform Variations:** These mappings may not work exactly for every CI/CD platform, runner, or plugin version you are using. Always consult the official documentation for your specific environment.
* **Custom Variables:** If a required field isn't directly available, simply define an environment variable (e.g., DEPLOYMENT\_ID, START\_TIME) early in your pipeline and reuse it in the final API call.
* **Timestamp Handling:** The mechanism to capture timestamps varies widely across platforms (e.g., GitHub custom actions, Jenkins plugins, Azure job context). Pick the most reliable approach for your specific setup.&#x20;
  {% endhint %}

***

#### 8. How to Send Events <a href="#id-8-how-to-send-events" id="id-8-how-to-send-events"></a>

You can send the event using:

1. **Inline Script**: curl from shell, or PowerShell Invoke-RestMethod.
2. **Platform Webhooks**: GitLab Integrations, GitHub Webhooks, or Argo Notifications.

**Security Note**: Store the API token in your CI/CD secrets manager. Do not hardcode it in plain text.

#### 9. Example Requests <a href="#id-9-example-requests" id="id-9-example-requests"></a>

**v2 – Single Completed Event**

```javascript
curl -X POST http://<client-host-or-domain>:8113/api/hooks/v2/deployment \
  -H "X-API-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_id": "deploy-20250922-1200",
    "event_type": "completed",
    "status": "success",
    "repo_url": "https://github.com/hivelai/webhook-logger",
    "commit_hash": "abc123def456789012345678901234567890abcd",
    "environment": "production",
    "start_time": "2025-09-22T12:00:00Z",
    "end_time": "2025-09-22T12:15:30Z",
    "branch": "main",
    "build_number": "12345",
    "pr_number": "71",
    "pr_numbers": [71,35,23],
    "image": "company/api-service:v1.2.3",
    "logs_url": "https://logs.example.com/deploy/20250922-1200"
  }'
```

#### 10. Example Responses <a href="#id-10-example-responses" id="id-10-example-responses"></a>

**Success:**

```json
{
  "message": "Deployment event stored successfully",
  "deployment_id": "deploy-20250922-1200",
  "success": true
}
```

**Validation Error:**

```json
{
  "message": "Validation failed",
  "error": "Start time cannot be after end time",
  "details": null,
  "correlation_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"
}
```

**Conflict (409):**

```json
{
  "message": "Duplicate deployment event",
  "error": "deployment event already exists for deployment_id=deploy-20250922-1200, event_type=completed",
  "details": null,
  "correlation_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"
}
```

`correlation_id` is either the client's own `X-Correlation-Id` request header, if sent, or a server-generated UUID.

A request body that fails to parse as valid JSON, or has a field of the wrong type (e.g. a number where a string is expected), returns a \`**400 Bad Request**\` with the specific parse error in \`**error**\`:

```
{
  "message": "Validation failed",
  "error": "Invalid JSON request body: json: cannot unmarshal number into Go struct field .pr_number of type string",
  "details": null,
  "correlation_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"
}
```

#### 11. Recommended Usage Flow <a href="#id-11-recommended-usage-flow" id="id-11-recommended-usage-flow"></a>

1. Generate API token in Hivel Settings.
2. Extract fields (repo, commit, timestamp) from your CI/CD environment variables.
3. Send POST request via your pipeline configuration.

Hivel processes the data to update DORA metrics automatically.

***

[^1]: