Skip to main content
Security Warning: This endpoint requires trusted network access and exposes sensitive webhook processing data including tokens and system information. Deploy only on private networks (VPN, internal). See Log Viewer Security.

​
Endpoint

GET /logs/api/step-logs/{hook_id}/{step_name}
Retrieve log entries that occurred during a specific workflow step’s execution window. This endpoint provides time-based correlation of log entries with workflow steps, allowing detailed analysis of what happened during each operation.

​
Parameters

​
hook_id
string
required
GitHub webhook delivery ID (X-GitHub-Delivery header value)Example: f4b3c2d1-a9b8-4c5d-9e8f-1a2b3c4d5e6fMust be between 1 and 100 characters
​
step_name
string
required
Name of the workflow step to retrieve logs forExamples:
  • clone_repository
  • webhook_routing
  • assign_reviewers
  • run_tox_tests
Must be between 1 and 100 characters

​
Response

​
step
object
Metadata about the workflow step
​
logs
array
Array of log entries that occurred during step execution
​
log_count
number
Total number of log entries found for the step

​
Use Cases

  1. Debug step failures - See exactly what happened during a failed operation
  2. Performance analysis - Identify slow operations within a step
  3. Audit trail - Track all actions taken during a specific operation
  4. Error investigation - View full error context and stack traces
  5. API debugging - See GitHub API calls and responses for a step
  6. Configuration verification - Check what configuration was used

​
Examples

​
Basic Request

curl "http://localhost:5000/logs/api/step-logs/f4b3c2d1-a9b8-4c5d-9e8f-1a2b3c4d5e6f/clone_repository"

​
Successful Step Response

{
  "step": {
    "name": "clone_repository",
    "status": "completed",
    "timestamp": "2024-01-15T10:00:05.123456Z",
    "duration_ms": 14444
  },
  "logs": [
    {
      "timestamp": "2024-01-15T10:00:05.123456Z",
      "level": "INFO",
      "logger_name": "GithubWebhook",
      "message": "Starting repository clone for myk-org/github-webhook-server",
      "hook_id": "f4b3c2d1-a9b8-4c5d-9e8f-1a2b3c4d5e6f",
      "event_type": "pull_request",
      "repository": "myk-org/github-webhook-server"
    },
    {
      "timestamp": "2024-01-15T10:00:05.234567Z",
      "level": "DEBUG",
      "logger_name": "GithubWebhook",
      "message": "Cloning branch: main, commit: abc123def456",
      "hook_id": "f4b3c2d1-a9b8-4c5d-9e8f-1a2b3c4d5e6f",
      "repository": "myk-org/github-webhook-server"
    },
    {
      "timestamp": "2024-01-15T10:00:19.567890Z",
      "level": "INFO",
      "logger_name": "GithubWebhook",
      "message": "Repository cloned successfully (15.2 MB)",
      "hook_id": "f4b3c2d1-a9b8-4c5d-9e8f-1a2b3c4d5e6f",
      "repository": "myk-org/github-webhook-server"
    }
  ],
  "log_count": 3
}

​
Failed Step Response

{
  "step": {
    "name": "assign_reviewers",
    "status": "failed",
    "timestamp": "2024-01-15T10:00:20.123456Z",
    "duration_ms": 111,
    "error": {
      "message": "API rate limit exceeded",
      "type": "GitHubException",
      "traceback": "Traceback (most recent call last):\n  File \"webhook_server/libs/handlers/owners_files_handler.py\", line 442..."
    }
  },
  "logs": [
    {
      "timestamp": "2024-01-15T10:00:20.123456Z",
      "level": "INFO",
      "logger_name": "OwnersFileHandler",
      "message": "Assigning reviewers based on OWNERS file",
      "hook_id": "f4b3c2d1-a9b8-4c5d-9e8f-1a2b3c4d5e6f",
      "pr_number": 123
    },
    {
      "timestamp": "2024-01-15T10:00:20.234567Z",
      "level": "ERROR",
      "logger_name": "OwnersFileHandler",
      "message": "Failed to assign reviewers: API rate limit exceeded",
      "hook_id": "f4b3c2d1-a9b8-4c5d-9e8f-1a2b3c4d5e6f",
      "pr_number": 123
    }
  ],
  "log_count": 2
}

​
Error Responses

​
404
object
Hook ID not found in logs
{
  "detail": "Hook ID not found: f4b3c2d1..."
}
​
404
object
Step name not found for the given hook ID
{
  "detail": "Step 'invalid_step' not found for hook_id: f4b3c2d1..."
}
​
500
object
Internal server error
{
  "detail": "Error retrieving step logs: <error message>"
}

​
Common Step Names

The following step names are commonly used in webhook processing workflows:
Step NameDescription
webhook_validationWebhook signature and payload validation
payload_parsingJSON payload parsing and field extraction
webhook_routingRouting webhook to appropriate handler
clone_repositoryClone repository from GitHub
assign_reviewersAssign OWNERS-based reviewers to PR
update_labelsUpdate PR labels (size, status, branch)
run_tox_testsExecute tox test suite
build_containerBuild and push container image
publish_pypiPublish package to PyPI
check_can_mergeValidate PR merge readiness
create_tracking_issueCreate PR tracking issue
cleanupCleanup temporary files and resources
Use the Workflow Steps endpoint to get a complete list of all steps for a specific webhook delivery.

​
Security Considerations

This endpoint is restricted to trusted networks only and includes an additional require_trusted_network dependency check. It will reject requests from public IP addresses. Allowed network ranges:
  • Private networks (RFC 1918): 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
  • Loopback addresses: 127.0.0.0/8
  • Link-local addresses: 169.254.0.0/16
For production deployments, always use a VPN or deploy behind a reverse proxy with authentication.

Workflow Steps

View all workflow steps and execution timeline

PR Flow

High-level PR workflow visualization

Log Entries

Query historical webhook logs

Security Guide

Log viewer security best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us