Webhooks API

The Webhooks API enables external systems to integrate with Blueberry IDP by sending event notifications and triggering actions.

Overview

Webhooks allow external services like GitLab, GitHub, ArgoCD, and other CI/CD systems to notify Blueberry about events such as:

• Pipeline completions
• Code pushes and pull requests
• Environment status changes
• Custom integration events

Authentication

Webhook endpoints have different authentication requirements:

• Generic Webhooks: No authentication required
• GitLab Webhooks: X-Gitlab-Token header
• GitHub Webhooks: X-GitHub-Event header + signature validation
• Environment Events: No authentication required

Endpoints

Generic Webhook

Accept any webhook payload for processing.

POST /api/webhooks/generic

Request Body

{
  "event": "custom_event",
  "message": "Custom webhook message",
  "data": {
    "key": "value"
  },
  "send_slack_notification": false,
  "timestamp": "2024-01-01T10:00:00Z"
}

Parameters

Response

{
  "status": "received",
  "message": "Webhook processed successfully",
  "webhook_id": "wh_abc123def456"
}

GitLab Pipeline Webhook

Handle GitLab CI/CD pipeline events.

POST /api/webhooks/gitlab/pipeline

Headers

X-Gitlab-Token: your-gitlab-webhook-token
Content-Type: application/json

Request Body

GitLab pipeline webhook payload (standard GitLab format):

{
  "object_kind": "pipeline",
  "object_attributes": {
    "id": 12345,
    "status": "success",
    "url": "https://gitlab.example.com/project/-/pipelines/12345",
    "created_at": "2024-01-01T10:00:00Z",
    "finished_at": "2024-01-01T10:15:00Z"
  },
  "project": {
    "id": 1,
    "name": "sample-project",
    "path_with_namespace": "group/sample-project",
    "web_url": "https://gitlab.example.com/group/sample-project"
  },
  "commit": {
    "id": "abc123def456",
    "short_id": "abc123",
    "title": "Fix authentication bug",
    "message": "Fix authentication bug\n\nDetailed description...",
    "author_name": "John Developer",
    "author_email": "john@example.com"
  },
  "builds": [
    {
      "id": 101,
      "stage": "build",
      "name": "build-backend",
      "status": "success"
    },
    {
      "id": 102,
      "stage": "test",
      "name": "run-tests",
      "status": "success"
    }
  ]
}

Response

{
  "status": "processed",
  "message": "GitLab pipeline webhook processed",
  "actions_taken": [
    "environment_created",
    "slack_notification_sent"
  ]
}

Pipeline Status Handling

GitHub Webhook

Handle GitHub repository events.

POST /api/webhooks/github

Headers

X-GitHub-Event: push
X-GitHub-Delivery: 12345678-1234-1234-1234-123456789abc
X-Hub-Signature-256: sha256=<signature>
Content-Type: application/json

Supported Events

• push - Code push events
• pull_request - Pull request events
• workflow_run - GitHub Actions workflow events

Request Body (Pull Request Example)

{
  "action": "opened",
  "number": 123,
  "pull_request": {
    "id": 456789,
    "number": 123,
    "title": "Add new feature",
    "body": "Description of the new feature",
    "state": "open",
    "head": {
      "ref": "feature/new-feature",
      "sha": "abc123def456"
    },
    "base": {
      "ref": "main",
      "sha": "def456abc123"
    },
    "user": {
      "login": "developer",
      "email": "developer@example.com"
    }
  },
  "repository": {
    "name": "sample-repo",
    "full_name": "org/sample-repo",
    "clone_url": "https://github.com/org/sample-repo.git"
  }
}

Response

{
  "status": "processed",
  "message": "GitHub webhook processed",
  "environment_created": true,
  "environment_id": "pr-123"
}

Environment Event Webhook

Handle environment lifecycle events.

POST /api/webhooks/environment/event

Request Body

{
  "event_type": "created",
  "environment_id": "pr-123",
  "environment_name": "pr-123",
  "status": "ready",
  "user_email": "developer@example.com",
  "repository": "org/sample-repo",
  "branch": "feature/new-feature",
  "commit_sha": "abc123def456",
  "urls": {
    "backend": "https://pr-123-backend.ephemeral.blueberry.florenciacomuzzi.com",
    "frontend": "https://pr-123-frontend.ephemeral.blueberry.florenciacomuzzi.com",
    "argocd": "https://argocd.florenciacomuzzi.com/applications/env-pr-123"
  },
  "metadata": {
    "ttl_hours": 24,
    "config_set": "default"
  }
}

Event Types

Response

{
  "status": "received",
  "message": "Environment event processed",
  "notifications_sent": ["slack", "email"]
}

Webhook Security

GitLab Token Validation

Configure webhook token in GitLab project settings:

1. Go to Project → Settings → Webhooks
2. Set Secret Token to your webhook token
3. Configure webhook URL: https://blueberry.florenciacomuzzi.com/api/webhooks/gitlab/pipeline

GitHub Signature Validation

GitHub webhooks are validated using HMAC-SHA256:

import hmac
import hashlib

def verify_github_signature(payload, signature, secret):
    """Verify GitHub webhook signature."""
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature)

Rate Limiting

Webhook endpoints have higher rate limits:
- Generic/Environment: 1000 requests/minute
- GitLab/GitHub: 500 requests/minute per project

Examples

GitLab CI/CD Integration

Add to your .gitlab-ci.yml:

stages:
  - build
  - deploy
  - notify

deploy_environment:
  stage: deploy
  script:
    - echo "Environment will be created by webhook"
  only:
    - merge_requests

notify_webhook:
  stage: notify
  script:
    - |
      curl -X POST "${BLUEBERRY_WEBHOOK_URL}/api/webhooks/gitlab/pipeline" \
        -H "X-Gitlab-Token: ${GITLAB_WEBHOOK_TOKEN}" \
        -H "Content-Type: application/json" \
        -d @webhook_payload.json
  when: always

GitHub Actions Integration

Add to your workflow:

name: Deploy Environment

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Environment Creation
        uses: distributhor/workflow-webhook@v2
        env:
          webhook_url: ${{ secrets.BLUEBERRY_WEBHOOK_URL }}
          webhook_secret: ${{ secrets.BLUEBERRY_WEBHOOK_SECRET }}
        with:
          webhook_url: ${{ env.webhook_url }}/api/webhooks/github
          data: ${{ toJson(github) }}

Custom Integration

Send custom webhook from any system:

#!/bin/bash
# Custom deployment notification

curl -X POST "https://blueberry.florenciacomuzzi.com/api/webhooks/generic" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "deployment_completed",
    "message": "Production deployment completed successfully",
    "data": {
      "version": "v1.2.3",
      "environment": "production",
      "deployer": "ci-system"
    },
    "send_slack_notification": true
  }'

Webhook Debugging

Test Webhook Delivery

Use the webhook test endpoints:

# Test generic webhook
curl -X POST "https://blueberry.florenciacomuzzi.com/api/webhooks/generic" \
  -H "Content-Type: application/json" \
  -d '{"test": true, "message": "Test webhook"}'

# Test GitLab webhook
curl -X POST "https://blueberry.florenciacomuzzi.com/api/webhooks/gitlab/pipeline" \
  -H "X-Gitlab-Token: test-token" \
  -H "Content-Type: application/json" \
  -d '{"object_kind": "pipeline", "object_attributes": {"status": "success"}}'

Webhook Logs

Check webhook processing logs:

# Get webhook logs
kubectl logs -n blueberry deployment/blueberry-api | grep webhook

# Filter by webhook type
kubectl logs -n blueberry deployment/blueberry-api | grep "gitlab_webhook"

Common Issues

Webhook Payload Validation

Required Fields

All webhooks should include:

{
  "timestamp": "2024-01-01T10:00:00Z",
  "source": "gitlab|github|custom",
  "event_type": "string"
}

Optional Notification Fields

{
  "send_slack_notification": true,
  "slack_channel": "#deployments",
  "notification_template": "custom"
}

Related Documentation

• GitLab Integration Workflow
• GitHub Integration Workflow
• Environment Events
• Notification Configuration

Last Updated: January 2024