Webhook User Guide

Overview

The webhook functionality is designed to:

• Validate incoming GitHub webhook events.
• Process repositories if specific files (e.g., Dobbuild.yaml) are modified.
• Execute DevOps workflows based on the content of the Dobbuild.yaml file.

API Endpoints

1. Generate API Key

Endpoint: /generate-api-key

Method: POST

Description: Generates a new API key for authentication purposes.

Response:

201 (Success):
{
  "status": "success",
  "name": "Generated API Key Name",
  "token": "Generated API Key Token"
}
500 (Error):
{
  "status": "error",
  "message": "Error details"
}
      

2. Generate Webhook Secret

Endpoint: /generate-webhook-secret

Method: POST

Description: Generates a new secret key for webhook validation.

Response:

201 (Success):
{
  "status": "success",
  "webhook_secret": "Generated Webhook Secret"
}
500 (Error):
{
  "status": "error",
  "message": "Error details"
}
      

3. Handle Webhook

Endpoint: /webhook

Method: POST

Description: Processes incoming webhook events from GitHub.

Features:

• Validates the webhook signature using the secret key.
• Processes only push events.
• Checks if the Dobbuild.yaml file is modified.
• Clones the repository and executes the Dobbuild.yaml if present.

Expected Headers:

• X-GitHub-Event: Specifies the event type (e.g., push).
• X-Hub-Signature-256: Contains the SHA256 HMAC signature of the payload.

Response:

200 (Ignored Event):
{
  "status": "ignored",
  "event": "event_type"
}
403 (Invalid Signature):
{
  "error": "Invalid GitHub signature"
}
500 (Processing Error):
{
  "error": "Failed to process payload: Error details"
}
      

CLI Commands

1. Regenerate Webhook Secret

Command: regenerate-webhook-secret

Description: Regenerates the webhook secret key for validating incoming requests.

Output:

New webhook secret generated: <Generated Secret>
      

Webhook Signature Verification

Function: verify_signature(payload, signature, secret)

Purpose: Validates the HMAC signature of the payload using the stored webhook secret.

Process:

• Splits the signature into hash type and value.
• Generates a HMAC signature using the payload and secret.
• Compares the generated signature with the received signature.

Returns:

• True if signatures match.
• False otherwise.

Repository Processing

Steps:

Clone the Repository:

• Clones the repository using the provided URL and branch.
• Ensures the repository is cloned to a fresh directory.

Execute Dobbuild.yaml:

• Checks if Dobbuild.yaml is modified and exists in the repository.
• Executes the file using the dob CLI command.
• Logs the output and saves execution results.

Generate Results Path:

• Determines the path for saving execution results.
• Limits the number of build files to 100 per repository.

Function Highlights:

• get_next_build_file_path: Generates the next available build file path.
• execute_dob_command: Executes the dob command and logs results.
• process_repository: Handles repository cloning, validation, and execution.

Webhook Processing Flow

Receive Webhook:

• Checks the event type from X-GitHub-Event header.
• Processes only push events.

Validate Signature:

• Ensures the payload's HMAC signature matches the stored secret.

Parse Payload:

• Extracts repository details and modified files.

Check for Changes in Dobbuild.yaml:

• Aborts processing if Dobbuild.yaml is not modified.

Clone and Process Repository:

• Clones the repository and executes the specified Dobbuild.yaml.

Return Response:

• Provides appropriate success or error responses.

Error Handling

Invalid Signature:

Returns a 403 Forbidden response with an error message.

File Not Found:

Aborts if the required Dobbuild.yaml file is missing.

Execution Errors:

Logs and returns details of subprocess or unexpected errors.

By following this guide, users can efficiently utilize the webhook functionality for automated processing of DevOps workflows.