Webhooks API

Handle incoming webhooks from GitHub and GitLab, and auto-register webhooks for CI/CD integration.


POST /api/webhooks/github

Receives GitHub webhook events. Supports push and pull_request events. Signature verification is performed using x-hub-signature-256.

Events handled:

  • Push to main/master: Triggers a staging deployment via GitLab pipeline.
  • Push to other branches: Creates a preview environment with K8s deployment and posts a ClickUp comment if the branch name contains a task ID.
  • PR opened/synchronized: Deploys a preview environment.
  • PR closed (unmerged): Terminates the preview environment.

Auth: Bearer token (authenticated)

Headers:

x-hub-signature-256: sha256=...
x-github-event: push

Example GitHub push payload (simplified):

{
  "ref": "refs/heads/main",
  "after": "abc123",
  "repository": {
    "clone_url": "https://github.com/org/my-app.git"
  }
}

Response 200:

{
  "success": true,
  "message": "Staging deploy triggered"
}

POST /api/webhooks/gitlab

Receives GitLab webhook events. Supports Push Hook and Merge Request Hook events. Token verification is performed using x-gitlab-token.

Events handled:

  • Push to main/master: Triggers a staging deployment.
  • Push to other branches: Deploys a preview environment and posts a ClickUp comment.
  • MR opened/updated: Deploys a preview environment.
  • MR closed/merged: Terminates or marks the preview deployment.

Auth: Bearer token (authenticated)

Headers:

x-gitlab-token: shared-secret
x-gitlab-event: Push Hook

Example GitLab push payload (simplified):

{
  "ref": "refs/heads/main",
  "after": "abc123",
  "project": {
    "http_url": "https://gitlab.com/org/my-app.git"
  }
}

Response 200:

{
  "success": true,
  "message": "Staging deploy triggered"
}

POST /api/cicd/register-webhook/:projectId

Auto-registers a webhook on GitHub or GitLab for a project. Detects the provider from the project's repositoryUrl. Requires DEVOPS or TECH_LEAD role.

Auth: Bearer token (DEVOPS, TECH_LEAD)

GitLab Registration: Creates a webhook with push_events and merge_requests_events enabled. Requires GITLAB_TOKEN environment variable.

GitHub Registration: Creates a webhook for push and pull_request events. Requires GITHUB_TOKEN and GITHUB_WEBHOOK_SECRET environment variables.

Response 200 (GitLab):

{
  "success": true,
  "message": "Webhook registered on GitLab",
  "webhookUrl": "https://api.example.com/api/webhooks/gitlab"
}

Response 200 (GitHub):

{
  "success": true,
  "message": "Webhook registered on GitHub",
  "webhookUrl": "https://api.example.com/api/webhooks/github"
}

Error 400:

{ "error": "No repository URL configured for this project" }

Error 500:

{ "error": "GitLab webhook registration failed: ..." }

Error Codes

Status Error Description
401 Invalid signature GitHub signature verification failed
401 Invalid token GitLab token verification failed
400 No repository URL... Project has no repositoryUrl set
400 Unsupported repository... Only GitHub and GitLab are supported
500 GITLAB_TOKEN not configured Missing env var for registration
500 GITHUB_TOKEN and... Missing env vars for registration