Deployment Events API

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

---

🔗 Base URL

https://app.hivel.ai/hivelapi/v1

🔑 Authentication

All requests require an organization API token. Pass this in the request header:

X-API-Token: YOUR_ORGANIZATION_API_TOKEN

---

1. Retrieving Your API Key

1. Open the Hivel application and navigate to Integrations under Settings.

2. Click on Connect on Hivel API Authorization card

   
3. Follow the given steps to start your integration

4. By clicking on Generate your API Key will be generated.

---

2. Deployment Events API

Endpoint

POST /hivelapi/v1/deployment

Description

Records deployment lifecycle events (started/completed) for an application. These events help track deployment frequency, duration, and reliability metrics.

Headers

• Content-Type: application/json

• X-API-Token: YOUR_ORGANIZATION_API_TOKEN

Request Body

Field	Type	Required	Description	Valid Values / Format
deployment_id	string	Yes	Unique identifier for the deployment run	Any string
event_type	string	Yes	Type of event	"started", "completed"
status	string	Yes	Deployment status	"success", "failed", "canceled", "unknown"
repo_url	string	Yes	Repository URL	Valid URL
commit_hash	string	Yes	Git commit hash	40-char SHA hash
branch	string	No	Git branch name	Any string
timestamp	string	Yes	Time of event	ISO 8601 datetime
environment	string	Yes	Deployment environment	"production", "staging", "dev", "custom"
build_number	string	No	CI/CD build number	Any string
pr_number	string	No	Pull request number	Any string
image	string	No	Docker image or artifact identifier	Any string
logs_url	string	No	Link to deployment logs	Valid URL

Example Requests

Deployment Started

curl -X POST https://app.hivel.ai/hivelapi/v1/deployment \
  -H "Content-Type: application/json" \
  -H "X-API-Token: 021A13A853AE2131D546199C9CD047932B168A3A36DD6CFF9527720AB2B40ABC" \
  -d '{
    "deployment_id": "deploy-1960-prod-001",
    "event_type": "started",
    "status": "unknown",
    "repo_url": "https://github.com/hivel/webhook-logger",
    "commit_hash": "abc123def456789012345678901234567890abcd",
    "branch": "main",
    "timestamp": "2024-12-21T14:30:00",
    "environment": "production",
    "build_number": "128",
    "pr_number": "461",
    "image": "webhook-logger:v1.2.8",
    "logs_url": "https://jenkins.hivel.ai/job/webhook-logger/128/console"
  }'

✅ Deployment Completed

curl -X POST https://app.hivel.ai/hivelapi/v1/deployment \
  -H "Content-Type: application/json" \
  -H "X-API-Token: 021A13A853AE2131D546199C9CD047932B168A3A36DD6CFF9527720AB2B40ABC" \
  -d '{
    "deployment_id": "deploy-1960-prod-001",
    "event_type": "completed",
    "status": "success",
    "repo_url": "https://github.com/hivel/webhook-logger",
    "commit_hash": "abc123def456789012345678901234567890abcd",
    "branch": "main",
    "timestamp": "2024-12-21T14:35:00",
    "environment": "production",
    "build_number": "128",
    "pr_number": "461",
    "image": "webhook-logger:v1.2.8",
    "logs_url": "https://jenkins.hivel.ai/job/webhook-logger/128/console"
  }'

Example Responses

✅ Success

{ "success": true, "message": "Deployment event stored successfully" }

❌ Missing Token

{ "success": false, "message": "Missing X-API-Token header", "error": "Unauthorized" }

❌ Invalid Token

{ "success": false, "message": "Invalid API token", "error": "Unauthorized" }

❌ Duplicate Event

{ "success": false, "message": "Duplicate deployment event ignored", "error": "Deployment event already exists: deploymentId=deploy-1960-prod-001, eventType=started, organizationId=1960" }

❌ Validation Error

{ "success": false, "message": "Validation failed", "errors": { "deployment_id": "deployment_id is required", "event_type": "event_type is required", "status": "status is required", "repo_url": "repo_url is required", "commit_hash": "commit_hash is required", "timestamp": "timestamp is required", "environment": "environment is required" } }

---

Usage Workflow

Generate a Token

Use the API to get a token from Step 1

Send Deployment Events

• Send a "started" event when deployment begins.

• Send a "completed" event when deployment finishes.

Both events use the same /deployment endpoint - only the payload changes.

---