Testing Dokploy webhook endpoints manually

dokploy-webhook-testing.md

Testing Dokploy Webhook Endpoints

Problem

When attempting to manually test a Dokploy webhook endpoint for auto-deployment, the API returns a "Branch Not Match" error:

{
    "message": "Branch Not Match"
}

Solution

Dokploy webhook endpoints expect requests to mimic the format of actual Git provider webhooks, particularly GitHub's webhook format. The key requirement is the X-GitHub-Event header.

Working Command

curl -X POST https://dokploy.knowsuchagency.com/api/deploy/compose/g9_VUyDCSqM5wzxeplg51 \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -d '{"ref":"refs/heads/main","repository":{"full_name":"test/repo"}}'

Expected Response

{
    "message": "Compose deployed successfully"
}

Key Requirements

1. X-GitHub-Event Header: Must be set to push to indicate a push event
2. ref Field: Must match the format refs/heads/BRANCH_NAME where BRANCH_NAME matches the branch configured in Dokploy
3. repository Field: Should include at minimum a full_name property
4. Content-Type: Must be application/json

Common Pitfalls

• Missing the X-GitHub-Event header will cause "Branch Not Match" errors
• The branch name in the ref field must exactly match what's configured in Dokploy
• The ref must use the full format refs/heads/BRANCH_NAME, not just the branch name

For Different Branches

To test with a different branch, modify the ref field:

# For master branch
curl -X POST https://dokploy.knowsuchagency.com/api/deploy/compose/YOUR_ID \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -d '{"ref":"refs/heads/master","repository":{"full_name":"test/repo"}}'

# For develop branch
curl -X POST https://dokploy.knowsuchagency.com/api/deploy/compose/YOUR_ID \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -d '{"ref":"refs/heads/develop","repository":{"full_name":"test/repo"}}'