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

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.

base url: http://<client-host-or-domain>:8113

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.

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

All API requests require an Organization API Key.

Headers:

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

How to Retrieve Your API Key:

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

1. Click on Connect on Deployment API card.

1. Follow steps to Generate API key.

3. API Overview

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.

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.

4. Required Fields

v2 (Single event: completed)

Note: Hivel calculates duration as end_time - start_time.

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	Git repo URL. e.g Web URL (or HTML URL): https://github.com/hivelai/webhook-logger Git Clone URL: https://github.com/hivelai/webhook-logger.git
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	Optional.
pr_numbers	No	Optional.
build_number	No	Optional metadata.
image	No	Optional metadata.
logs_url	No	Optional metadata.

Note: Hivel does not use pull request URLs or numbers to decide which team a deployment belongs to. The team comes from the repository mappings set up on the Team Mapping page, so make sure the repository in repo_url is mapped to a team.

5. Accepted Timestamp Formats

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

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

💡 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.

Mapping Reference

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

7. Common CI/CD Field Mapping

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>

⚠️ 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.

---

8. How to Send Events

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

v2 – Single Completed Event

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

Success:

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

Validation Error:

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

Conflict (409):

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

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.

---