Hivel-managed

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

The base URL for accessing Hivel is: https://app.hivel.ai

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 the Hivel application and navigate to Integrations under Settings.

1. Click on Connect in 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.

Hivel computes DORA metrics such as deployment frequency from submitted events via a daily batch job.

4. Required Fields

v2 (Single event: completed)

Note: Hivel calculates duration as end_time - start_time.

Field	Type	Required	Notes
deployment_id	string	Yes	Must be unique.
event_type	string	Yes	Must be "completed".
status	string	Yes	"success", "failed", "canceled", "unknown
start_time	string	Yes	Deployment start timestamp.
end_time	string	Yes	Deployment end timestamp.
repo_url	string	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	string	Yes	production / staging / dev / etc (string value).
branch	string	Yes	Branch name on which CI/CD is running.
commit_hash	string	No	Yes, if available.
pr_number	string	No	Optional.
pr_numbers	array of integers	No	Optional.
build_number	string	No	Optional metadata.
image	string	No	Optional metadata.
logs_url	string	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. start_time and end_time are always sent as JSON strings, even when the value itself is numeric (epoch).

• ISO / RFC 3339

  • "2025-11-19T10:20:32Z"

  • "2025-11-19T10:20:32.846Z"

• Epoch (as a string)

  • 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 → status = success phase = Failed | Error OR health = Degraded → status = failed Running / Progressing / Missing / Suspended → status = 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 https://app.hivel.ai/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"
}

Malformed or Mistyped Request Body:

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.