Webhooks

​

Overview

• GitHub (HMAC-SHA256 signature verification)
• GitLab (token-based verification)

1. Verifies the signature/token
2. Checks if the repository is registered
3. Creates a new scan at the pushed commit SHA
4. Triggers the full scan pipeline
5. Returns a 200 OK response with scan details

​

Setting Up Webhooks

​

Generate a Webhook Secret

openssl rand -hex 20

WEBHOOK_SECRET=your_generated_secret_here

​

Configure Your Git Provider

​

Signature Verification

​

GitHub (HMAC-SHA256)

1. GitHub generates: HMAC-SHA256(secret, payload)
2. Sends signature in header: X-Hub-Signature-256: sha256=<hex_digest>
3. Heimdall recomputes the signature using the payload and WEBHOOK_SECRET
4. Signatures are compared in constant-time to prevent timing attacks

fn verify_github_signature(secret: &str, body: &[u8], signature_header: &str) -> bool {
    use hmac::{Hmac, Mac};
    use sha2::Sha256;
    
    let Some(hex_sig) = signature_header.strip_prefix("sha256=") else {
        return false;
    };
    let Ok(expected) = hex::decode(hex_sig) else {
        return false;
    };
    let Ok(mut mac) = HmacSha256::new_from_slice(secret.as_bytes()) else {
        return false;
    };
    mac.update(body);
    mac.verify_slice(&expected).is_ok()
}

​

GitLab (Token)

1. GitLab sends the secret token in header: X-Gitlab-Token: <secret>
2. Heimdall compares the token to WEBHOOK_SECRET (exact string match)
3. Mismatch returns 401 Unauthorized

​

Supported Events

​

Push Events

{
  "ref": "refs/heads/main",
  "after": "abc123...",
  "repository": {
    "full_name": "owner/repo",
    "clone_url": "https://github.com/owner/repo.git"
  }
}

{
  "object_kind": "push",
  "ref": "refs/heads/main",
  "after": "abc123...",
  "project": {
    "path_with_namespace": "owner/repo",
    "http_url": "https://gitlab.com/owner/repo.git"
  }
}

​

Ignored Events

• Pull requests / Merge requests
• Issues
• Comments
• Releases

{
  "status": "ok",
  "data": {
    "status": "ignored",
    "reason": "event type 'pull_request' is not handled"
  }
}

​

Webhook Response

​

Successful Scan Trigger

{
  "status": "ok",
  "data": {
    "status": "scan_triggered",
    "scan_id": "550e8400-e29b-41d4-a716-446655440000",
    "repo_id": "660e8400-e29b-41d4-a716-446655440000",
    "commit_sha": "abc123def456...",
    "ref": "refs/heads/main"
  }
}

​

Repository Not Found

{
  "status": "error",
  "code": 404,
  "message": "No registered repo matches URL: https://github.com/owner/repo.git"
}

​

Invalid Signature

{
  "status": "error",
  "code": 401,
  "message": "Invalid signature"
}

​

Troubleshooting

​

Webhook Secret Not Configured

# Generate a secret
openssl rand -hex 20

# Add to .env
echo "WEBHOOK_SECRET=<generated_secret>" >> .env

# Restart Heimdall
docker compose restart heimdall

​

Signature Verification Fails

• Webhook delivery shows “401 Unauthorized”
• Heimdall logs: “GitHub webhook signature verification failed”

1. Verify the secret in GitHub webhook settings matches WEBHOOK_SECRET
2. Check for extra whitespace in .env
3. Ensure Content-Type: application/json is set in GitHub

• Webhook test shows “401 Unauthorized”
• Heimdall logs: “GitLab webhook token verification failed”

1. Verify the token in GitLab webhook settings matches WEBHOOK_SECRET exactly
2. Check for trailing newlines or spaces in the secret

​

Repository Not Found

1. Verify the repository is added to Heimdall
2. Check the remote_url in the database matches the webhook payload:
   SELECT id, name, remote_url FROM repos;
   
3. Re-add the repository if URLs don’t match

​

Webhook Delays

1. Check WORKER_POLL_INTERVAL_SECS in .env (default: 5 seconds)
2. Reduce for faster scan starts:
   WORKER_POLL_INTERVAL_SECS=2
   
3. For development, disable worker mode for instant inline scans:
   WORKER_ENABLED=false
   

​

Firewall / Network Issues

1. Verify your webhook endpoint is publicly accessible:
   curl -X POST https://heimdall.example.com/webhooks/github \
     -H "Content-Type: application/json" \
     -d '{}'
   # Should return 400 (bad request) not connection refused
   
2. Check firewall rules allow inbound HTTPS
3. Verify DNS resolves correctly
4. For GitHub, check the IP allowlist: GitHub IP ranges

​

Security Best Practices

1. Always verify signatures: Never disable signature verification
2. Use HTTPS: Webhooks should only be sent to HTTPS endpoints in production
3. Rotate secrets periodically: Update WEBHOOK_SECRET and reconfigure webhooks
4. Limit webhook scope: Only subscribe to push events
5. Monitor failed deliveries: Set up alerts for repeated webhook failures

​

Testing Webhooks Locally

# Start Heimdall locally
cargo run --bin heimdall

# In another terminal, start ngrok
ngrok http 8080

# Use the ngrok URL for webhook configuration
# Example: https://abc123.ngrok.io/webhooks/github

​

API Reference