Git Webhooks

Automate deployments with GitHub, GitLab, and Gitea 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

1. Create Git stack

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

2. Enable webhook

   In the stack settings:

   1. Toggle Webhook Enabled
   2. Click Generate Secret (optional but recommended)
   3. Copy the webhook URL
3. 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

1. Open repository settings

   Navigate to your GitHub repository > Settings > Webhooks

2. 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
   
3. Select events

   Choose Just the push event (default)

4. 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.

GitLab

1. Open repository settings

   Navigate to your GitLab project > Settings > Webhooks

2. Add webhook

   Configure the webhook:

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

   Leave Enable SSL verification checked unless using self-signed certificates

4. 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

Gitea

1. Open repository settings

   Navigate to your Gitea repository > Settings > Webhooks

2. 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
   
3. Select events

   Choose Push events

4. Add webhook

   Click Add Webhook and test it

Generic Git

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:

1. Generate secret

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

2. Configure in Git

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

3. 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": "[e-mail]:user/repo.git"
  },
  "pusher": {
    "name": "username",
    "email": "[e-mail]"
  },
  "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": "[e-mail]:user/repo.git"
  },
  "user_name": "Username",
  "user_email": "[e-mail]",
  "commits": [
    {
      "id": "abc123...",
      "message": "Update compose file",
      "timestamp": "2024-03-04T12:00:00+00:00"
    }
  ]
}

Deployment Process

When a webhook is received:

1. Validate request

   • Verify webhook secret/signature
   • Check payload format
   • Validate repository ID
2. Check branch

   • Extract branch from ref field
   • Compare with configured branch
   • Skip if branch doesn’t match
3. Clone repository

   • Use configured Git credentials
   • Clone or pull latest changes
   • Checkout specified branch
4. Deploy stack

   • Parse compose file
   • Apply environment variables
   • Run docker compose up -d
5. 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

1. Navigate to Stacks > select stack > Deployments
2. 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:[e-mail]/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 repository

Parameters:

• 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 trigger

Query 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.

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

Next Steps

Git Integration

Learn more about Git stack management

Notifications

Configure deployment notifications