Git Webhooks

Dockhand supports Git webhooks for automatic stack deployments when code changes are pushed to your repository. Connect GitHub, GitLab, or any Git service to trigger updates automatically.

Overview

Webhooks enable continuous deployment by automatically pulling and deploying your compose stacks when changes are detected in your Git repository.

Configuration

Enable Webhooks

Create Git stack

Navigate to Stacks > Add from Git and connect your repository.

Enable webhook

In the stack settings:

Toggle Webhook Enabled
Click Generate Secret (optional but recommended)
Copy the webhook URL

Configure Git provider

Add the webhook URL to your Git repository settings.

Webhook URL Format

https://dockhand.example.com/api/git/webhook/{repository-id}

Or for individual stacks:

https://dockhand.example.com/api/git/stacks/{stack-id}/webhook

Git Provider Setup

GitHub
GitLab
Gitea
Generic Git

Open repository settings

Navigate to your GitHub repository > Settings > Webhooks

Add webhook

Click Add webhook and configure:

Payload URL: https://dockhand.example.com/api/git/webhook/1
Content type: application/json
Secret: your-webhook-secret

Select events

Choose Just the push event (default)

Save

Click Add webhook and GitHub will send a test ping

Signature Verification

GitHub signs webhook payloads with HMAC-SHA256:

X-Hub-Signature-256: sha256=abc123...

Dockhand automatically verifies this signature using your webhook secret.

Open repository settings

Navigate to your GitLab project > Settings > Webhooks

Add webhook

Configure the webhook:

URL: https://dockhand.example.com/api/git/webhook/1
Secret token: your-webhook-secret
Trigger: Push events

Enable SSL verification

Leave Enable SSL verification checked unless using self-signed certificates

Add webhook

Click Add webhook and test with Test > Push events

Signature Verification

GitLab uses a simple token in the header:

X-Gitlab-Token: your-webhook-secret

Open repository settings

Navigate to your Gitea repository > Settings > Webhooks

Add webhook

Click Add Webhook > Gitea and configure:

Target URL: https://dockhand.example.com/api/git/webhook/1
HTTP Method: POST
POST Content Type: application/json
Secret: your-webhook-secret

Select events

Choose Push events

Add webhook

Click Add Webhook and test it

Any Git service supporting webhooks can be configured:Requirements:

POST request to webhook URL
JSON payload
Optional signature/token authentication

Minimal payload:

{
  "ref": "refs/heads/main",
  "repository": {
    "url": "https://git.example.com/user/repo.git"
  }
}

Webhook Security

Secret Verification

Webhook secrets prevent unauthorized deployments:

Generate secret

In Dockhand, click Generate Secret for your webhook. This creates a secure random token.

Configure in Git

Add the secret to your Git provider’s webhook configuration.

Verification

Dockhand verifies every webhook request:

GitHub: Validates HMAC-SHA256 signature
GitLab: Compares X-Gitlab-Token header
Others: Checks custom signature or token

Always use webhook secrets in production. Without secrets, anyone who knows your webhook URL can trigger deployments.

Signature Validation

The webhook endpoint verifies signatures before processing:

function verifySignature(payload: string, signature: string, secret: string): boolean {
  // GitHub: sha256=<hmac>
  if (signature.startsWith('sha256=')) {
    const expectedSignature = 'sha256=' + 
      crypto.createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    );
  }
  
  // GitLab: direct token comparison
  return signature === secret;
}

Branch Filtering

Configure which branch triggers deployments:

Stack Configuration

Repository: https://github.com/user/app.git
Branch: main
Webhook Enabled: Yes

Only pushes to the configured branch will trigger deployments. Pushes to other branches are ignored.

Multiple Environments

Deploy different branches to different environments:

# Production Stack
Branch: main
Environment: Production

# Staging Stack
Branch: develop
Environment: Staging

Configure separate webhooks for each stack to deploy the correct branch.

Webhook Payload

Dockhand processes webhook payloads to extract repository information:

GitHub Payload

{
  "ref": "refs/heads/main",
  "repository": {
    "clone_url": "https://github.com/user/repo.git",
    "ssh_url": "[email protected]:user/repo.git"
  },
  "pusher": {
    "name": "username",
    "email": "[email protected]"
  },
  "commits": [
    {
      "id": "abc123...",
      "message": "Update compose file",
      "timestamp": "2024-03-04T12:00:00Z"
    }
  ]
}

GitLab Payload

{
  "ref": "refs/heads/main",
  "project": {
    "git_http_url": "https://gitlab.com/user/repo.git",
    "git_ssh_url": "[email protected]:user/repo.git"
  },
  "user_name": "Username",
  "user_email": "[email protected]",
  "commits": [
    {
      "id": "abc123...",
      "message": "Update compose file",
      "timestamp": "2024-03-04T12:00:00+00:00"
    }
  ]
}

Deployment Process

When a webhook is received:

Validate request

Verify webhook secret/signature
Check payload format
Validate repository ID

Check branch

Extract branch from ref field
Compare with configured branch
Skip if branch doesn’t match

Clone repository

Use configured Git credentials
Clone or pull latest changes
Checkout specified branch

Deploy stack

Parse compose file
Apply environment variables
Run docker compose up -d

Log event

Record deployment in audit log
Send notifications if configured
Update last sync timestamp

Manual Webhook Trigger

Trigger deployments manually via GET request:

curl "https://dockhand.example.com/api/git/webhook/1?secret=your-webhook-secret"

This is useful for:

Testing webhook configuration
Manual deployments outside Git workflow
Scheduled deployments via cron

The secret parameter must match the configured webhook secret.

Monitoring Webhooks

View Webhook History

Navigate to Stacks > select stack > Deployments
View deployment history with:
- Trigger source (webhook/manual)
- Timestamp
- Commit hash
- Status (success/failed)
- Duration

Audit Logs

Webhook events are recorded in audit logs:

{
  "action": "webhook",
  "entityType": "git_stack",
  "entityId": "1",
  "description": "Webhook deployment triggered",
  "details": {
    "source": "github",
    "branch": "main",
    "commit": "abc123...",
    "result": "deployed"
  },
  "timestamp": "2024-03-04T12:00:00Z"
}

Troubleshooting

Webhook not triggered

Verify webhook URL is correct and accessible from Git server
Check webhook is enabled in both Git and Dockhand
Review Git provider webhook delivery logs

Test webhook manually:

curl -X POST https://dockhand.example.com/api/git/webhook/1 \
  -H "Content-Type: application/json" \
  -d '{"ref": "refs/heads/main"}'

Check firewall allows inbound connections on webhook port

Signature verification failed

Verify webhook secret matches between Git and Dockhand
Check secret hasn’t expired or been regenerated
For GitHub, ensure Content-Type is application/json
Review webhook delivery logs in Git provider
Try regenerating the secret on both sides

Deployment failed

Check Git credentials are valid and not expired
Verify branch name matches configuration
Ensure compose file exists at configured path

Review deployment logs in Dockhand:

Stacks > [stack] > Deployments > [latest] > View Logs

Check Docker daemon is accessible from Dockhand

Wrong branch deployed

Verify branch configuration in stack settings
Check webhook payload includes correct ref field
Multiple stacks may be listening to same repository
Review webhook delivery logs for branch information

Advanced Configuration

Webhook with Basic Auth

If your Dockhand instance requires authentication:

https://username:[email protected]/api/git/webhook/1

Avoid embedding credentials in URLs. Use webhook secrets instead.

Custom Headers

Some Git providers support custom headers:

X-Custom-Header: value
Content-Type: application/json

Dockhand ignores custom headers but verifies standard authentication headers.

Webhook Retry Logic

Git providers retry failed webhooks:

GitHub: Retries up to 3 times over several hours
GitLab: Retries based on configuration (default: 3 times)
Gitea: Configurable retry count and interval

If deployment fails, Dockhand logs the error. Check deployment logs to diagnose issues.

API Reference

Webhook endpoints:

POST /api/git/webhook/{id}

endpoint

Trigger deployment for repositoryParameters:

id: Repository ID

Headers:

X-Hub-Signature-256: GitHub signature
X-Gitlab-Token: GitLab token

Response:

{
  "success": true,
  "message": "Deployment triggered"
}

GET /api/git/webhook/{id}

endpoint

Manual deployment triggerQuery Parameters:

secret: Webhook secret

Response:

{
  "success": true,
  "message": "Deployment started"
}

See full API Reference for details.

Security Best Practices

Webhook endpoints are publicly accessible. Always use secrets to verify authenticity.

Always use webhook secrets to verify requests
Enable HTTPS for webhook URLs (required for production)
Restrict webhook IPs in firewall if Git provider publishes IP ranges
Rotate secrets periodically (every 90 days)
Monitor webhook logs for suspicious activity
Use read-only tokens for Git credentials when possible
Audit deployments regularly to detect unauthorized changes

Overview

Getting Started

Core Features

Advanced Features

Authentication & Security

Deployment

Integrations

Overview

Configuration

Enable Webhooks

Webhook URL Format

Git Provider Setup

Signature Verification

Signature Verification

Webhook Security

Secret Verification

Signature Validation

Branch Filtering

Multiple Environments

Webhook Payload

GitHub Payload

GitLab Payload

Deployment Process

Manual Webhook Trigger

Monitoring Webhooks

View Webhook History

Audit Logs

Troubleshooting

Advanced Configuration

Webhook with Basic Auth

Custom Headers

Webhook Retry Logic

API Reference

Security Best Practices

Next Steps

Git Integration

Notifications

Build docs developers (and LLMs) love

Overview

Getting Started

Core Features

Advanced Features

Authentication & Security

Deployment

Integrations

​Overview

​Configuration

​Enable Webhooks

​Webhook URL Format

​Git Provider Setup

​Signature Verification

​Signature Verification

​Webhook Security

​Secret Verification

​Signature Validation

​Branch Filtering

​Multiple Environments

​Webhook Payload

​GitHub Payload

​GitLab Payload

​Deployment Process

​Manual Webhook Trigger

​Monitoring Webhooks

​View Webhook History

​Audit Logs

​Troubleshooting

​Advanced Configuration

​Webhook with Basic Auth

​Custom Headers

​Webhook Retry Logic

​API Reference

​Security Best Practices

​Next Steps

Git Integration

Notifications

Build docs developers (and LLMs) love

Overview

Configuration

Enable Webhooks

Webhook URL Format

Git Provider Setup

Signature Verification

Signature Verification

Webhook Security

Secret Verification

Signature Validation

Branch Filtering

Multiple Environments

Webhook Payload

GitHub Payload

GitLab Payload

Deployment Process

Manual Webhook Trigger

Monitoring Webhooks

View Webhook History

Audit Logs

Troubleshooting

Advanced Configuration

Webhook with Basic Auth

Custom Headers

Webhook Retry Logic

API Reference

Security Best Practices

Next Steps