DORA Metrics Webhooks

Overview

While Allstacks allows for seamless integration into many different build systems and tools in your environment, we recognize that there are many different types of deploy processes and build systems being used by our customers. This integration allows our customers to send data to the Allstacks platform that can be used to generate DORA metric reports and other metrics on your build and release process. This method is recommended if you either use a custom or in-house build system, or a build and deploy tool that we do not currently support. We provide a number of options to provide data to the system to customize both your metrics and the data ingested by the platform.

Prerequisite

CustomCD service is already created in your company.
- To create a CustomCD service, head to your organizations tool page.
- Once on the tools page, click Add tool and search for CustomCD.
- Create a unique name for your customCD such as ‘OrganizationName_Custom_CD' and click Add Tool.
Create a Personal Access Token
- Personal Access Tokens can be created by going to the personal access token page via the same dropdown described above.
- Once on this page click Create PAT.
- Give your PAT a unique name and an expiration date.

Endpoint to create a custom job

POST https://app.allstacks.com/webhook/company/<company_id>/cicd_job
- Note: For single tenet customers, app.allstacks.com should be replaced with your specific environment url.
Data should be sent as JSON body
Token should be sent in Authorization header

Header Key = ‘Authorization’

Header Value = ‘Bearer <token>’

Base Fields

job_id [Required] [String] - Custom string value to uniquely identify this job. Allstacks assumes this may not be truly unique, and will use a different value for the primary key. This will be stored as a property in allstacks.
commit_sha [Required] [String] - The full SHA of the commit being deployed. This means this will be a string of 40 characters OR 64 Characters for the new version that’s being rolled out. This will be stored as a property in allstacks.
service_id [Required] [Integer] - The ID of the Custom CD Service that this data will be routed to.
job_start_time [Required] [Integer] - The epoch timestamp of the start of the job. (i.e seconds since epoch). This will be stored as the item creation date and item start date of the service item.
job_duration [Required] [Integer] - The duration of the job in seconds, as an integer. This will be stored as a property in allstacks.
status [Required] [String] - This field indicates the status of the job. Valid values are ‘Succeeded’, ‘Failed’, ‘On Hold’. This will be stored as a property in allstacks.
repo_id OR repo_name [Required] [String] - One of repo id and repo name must be supplied. This will be stored as a property in allstacks.
triggered_by [Optional] [String] - The user email OR agent username that triggered the job. A service user will be created in allstacks for this user if one doesn’t already exist. If this field is blank, we will use a default value, ‘Custom CD Agent’. This will be stored as the item creation user of the service item.
job_type [Optional] [String] - A customer defined field that allows a user to distinguish between types of jobs. If this field is blank, we will use a default value, ‘CUSTOM_CD_JOB’. This will be stored as the item subtype of the service item.

Optional Fields

List of optional fields can be supplied. They will be stored as properties in allstacks. Maximum number of optional fields allowed is 20.
Valid types are ‘string’, ‘integer’, ‘float’, ‘duration’, ‘timestamp’
- duration type must be supplied as an integer
- timestamp type must be supplied as an integer i.e seconds since epoch
Value can be a single value or a list of values. (maximum limit is 20)
Format is {‘key’: ‘name of key’, ‘value’: ‘value’ / [list of values], ‘type’: ‘type of key’}

Examples

{
   "job_id": "1",
   "status": "Succeeded",
   "commit_sha": "a2e7da86cc392417b0d9f605b28038aae80b002f",
   "triggered_by": "testuser@org.com" 
   "repo_id": “12345”,
   "service_id": 2,
   "job_start_time": 1704018030,
   "job_duration": 300,
   "job_type": "Production Deploy",
   "optional": [
     {
       "key": 'microservice',
       "value": ['frontend', 'backend'],
       "type": 'string'
     },
     {
       "key": 'qa_approved_on',
       "value": 1704018030,
       "type": 'timestamp'
     },
   ]
}

import requests
import time
from typing import Optional, Union, List, Dict

class DORAMetricsClient:
    def __init__(self, company_id: str, token: str):
        """
        Initialize the DORA Metrics API client.
        
        Args:
            company_id: Your company ID
            token: Personal Access Token for authentication
        """
        self.base_url = f"https://app.allstacks.com/webhook/company/{company_id}/cicd_job"
        self.headers = {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        }

    def create_job(
        self,
        job_id: str,
        commit_sha: str,
        service_id: int,
        status: str,
        repo_id: Optional[str] = None,
        repo_name: Optional[str] = None,
        triggered_by: Optional[str] = None,
        job_type: Optional[str] = None,
        optional_fields: Optional[List[Dict]] = None
    ) -> requests.Response:
        """
        Create a new DORA metrics job.
        
        Args:
            job_id: Unique identifier for the job
            commit_sha: Full SHA of the commit being deployed
            service_id: ID of the Custom CD Service
            status: Job status ('Succeeded', 'Failed', or 'On Hold')
            repo_id: Repository ID (either repo_id or repo_name is required)
            repo_name: Repository name (either repo_id or repo_name is required)
            triggered_by: User email or agent username that triggered the job
            job_type: Customer-defined field to distinguish between job types
            optional_fields: List of additional fields to include
            
        Returns:
            Response from the API
        """
        if not repo_id and not repo_name:
            raise ValueError("Either repo_id or repo_name must be provided")

        payload = {
            "job_id": job_id,
            "commit_sha": commit_sha,
            "service_id": service_id,
            "job_start_time": int(time.time()),
            "job_duration": 0,  # Set initial duration to 0
            "status": status
        }

        # Add repo identifier
        if repo_id:
            payload["repo_id"] = repo_id
        else:
            payload["repo_name"] = repo_name

        # Add optional fields if provided
        if triggered_by:
            payload["triggered_by"] = triggered_by
        if job_type:
            payload["job_type"] = job_type
        if optional_fields:
            payload["optional"] = optional_fields

        return requests.post(self.base_url, headers=self.headers, json=payload)

def main():
    # Example usage
    client = DORAMetricsClient(
        company_id="your_company_id",
        token="your_personal_access_token"
    )

    # Example optional fields
    optional_fields = [
        {
            "key": "microservice",
            "value": ["frontend", "backend"],
            "type": "string"
        }
    ]

    # Create a new job
    try:
        response = client.create_job(
            job_id="deploy-123",
            commit_sha="a2e7da86cc392417b0d9f605b28038aae80b002f",
            service_id=2,
            status="Succeeded",
            repo_id="12345",
            triggered_by="developer@company.com",
            job_type="Production Deploy",
            optional_fields=optional_fields
        )
        
        if response.status_code == 200:
            print("Successfully created DORA metrics job")
            print(response.json())
        else:
            print(f"Failed to create job: {response.status_code}")
            print(response.text)
            
    except Exception as e:
        print(f"Error creating job: {str(e)}")

if __name__ == "__main__":
    main()

Confirming the data is being synced into Allstacks

Visual Confirmation

The most straightforward way to verify that your data is properly syncing with Allstacks is to check the scorecard page. This will allow you to confirm that the metrics displayed match your expectations based on the data you've submitted.

Programmatic Verification

For automated verification or integration testing, you can use the following API endpoint to programmatically confirm data synchronization:

Request:

POST https://app.allstacks.com/api/v1/organization/{company_id}/metrics_v2/metrics/
This requests takes basic authentication with a username and password
The body of the request should include the following JSON object

{
  "config": {
    "api": "metrics_v2",
    "views": [
      {
        "dimensions": [
          {
            "property": "id",
            "data_type": "integer"
          },
          {
            "property": "item_name",
            "data_type": "string"
          },
          {
            "property": "item_creation_date",
            "data_type": "date"
          }
        ]
      }
    ],
    "as_csv": false,
    "filters": {
      "default": {
        "item_type": "CUSTOM_CD_JOB"
      },
      "user_filters": {
        "include_disabled_users": true
      },
      "advanced_filters": {}
    }
  }
}

Allstacks Knowledge Base