Deployment Events API
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 URLs
The base URL for accessing Hivel may vary depending on your organization's configuration. Please make sure to select the appropriate base URL according to your setup.
The URL will be either of these:
https://app.hivel.ai OR https://app.hivel.in
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:
Open the Hivel application and navigate to Integrations under Settings.
Click on Connect on Deployment API card
Follow steps to Generate API key.
3. API Overview
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.
4. Required Fields
v2 (Single event: completed)
deployment_id
Yes
Must be unique.
event_type
Yes
Must be "completed".
status
Yes
"success", "failed", "cancelled", "unknown"
start_time
Yes
Deployment start timestamp.
end_time
Yes
Deployment end timestamp.
repo_url
Yes
Git repo URL.
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.
build_number
No
Optional metadata.
image
No
Optional metadata.
logs_url
No
Optional metadata.
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
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
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.
repo_url
${{ github.repository }}
$CI_PROJECT_URL
$GIT_URL
$(Build.Repository.Uri)
commit_hash
${{ github.sha }}
$CI_COMMIT_SHA
$GIT_COMMIT
$(Build.SourceVersion)
environment
${{ github.environment }}
$CI_ENVIRONMENT_NAME
$ENVIRONMENT
$(Release.EnvironmentName)
start_time
Step output
(e.g. steps.start.outputs.time)
$CI_JOB_STARTED_AT
$BUILD_ID / plugin timestamps
$(Build.StartTime)
end_time
Workflow end timestamp
$CI_JOB_FINISHED_AT
Timestamp + duration
$(Build.FinishTime)
⚠️ 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:
Inline Script: curl from shell, or PowerShell Invoke-RestMethod.
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
Note: timestamp is replaced by start_time and end_time.
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" }
11. Recommended Usage Flow
Generate API token in Hivel Settings.
Extract fields (repo, commit, timestamp) from your CI/CD environment variables.
Send POST request via your pipeline configuration.
Hivel processes the data to update DORA metrics automatically.
Last updated
Was this helpful?