# 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: 1. Open the Hivel application and navigate to Integrations under Settings. 2. Click on Connect on Deployment API card 1\. ```

``` 3. Follow steps to Generate API key. 1\. ```

``` ### 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. ### 4. Required Fields #### 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", "cancelled", "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):
Git Clone 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. | | pr\_numbers | 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`). {% hint style="success" %} 💡 **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. {% endhint %} #### 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>`

{% hint style="info" %} #### **⚠️ 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. {% endhint %} *** ### 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 **Note**: timestamp is replaced by start\_time and end\_time.


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" }'

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

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