Setting up Code-to-Docs

1 Add the workflow file

.github/workflows/docs-assistant.yml

name: Documentation Assistant on: issue_comment: types: [created] permissions: contents: read issues: write pull-requests: write jobs: docs-assistant: runs-on: ubuntu-latest if: | github.event.issue.pull_request && (contains(github.event.comment.body, '[review-docs]') || contains(github.event.comment.body, '[update-docs]') || contains(github.event.comment.body, '[review-feature]')) steps: - name: Get PR information id: pr_info if: github.event.issue.pull_request env: GH_TOKEN: ${{ secrets.GH_PAT }} run: | PR_NUMBER=${{ github.event.issue.number }} PR_DATA=$(gh api repos/${{ github.repository }}/pulls/$PR_NUMBER) HEAD_REF=$(echo "$PR_DATA" | jq -r '.head.ref') HEAD_REPO=$(echo "$PR_DATA" | jq -r '.head.repo.full_name') BASE_REF=$(echo "$PR_DATA" | jq -r '.base.ref') echo "head_ref=$HEAD_REF" >> $GITHUB_OUTPUT echo "head_repo=$HEAD_REPO" >> $GITHUB_OUTPUT echo "base_ref=$BASE_REF" >> $GITHUB_OUTPUT echo "pr_number=$PR_NUMBER" >> $GITHUB_OUTPUT - name: Checkout PR Code uses: actions/checkout@v4 with: repository: ${{ steps.pr_info.outputs.head_repo || github.repository }} ref: ${{ steps.pr_info.outputs.head_ref || github.ref }} fetch-depth: 0 token: ${{ secrets.GH_PAT }} - name: Documentation Assistant uses: redhat-community-ai-tools/code-to-docs@main with: model-api-base: ${{ secrets.MODEL_API_BASE }} model-api-key: ${{ secrets.MODEL_API_KEY }} model-name: ${{ secrets.MODEL_NAME }} docs-repo-url: ${{ secrets.DOCS_REPO_URL }} github-token: ${{ secrets.GH_PAT }} pr-number: ${{ github.event.issue.number }} pr-base: origin/${{ steps.pr_info.outputs.base_ref || 'main' }} pr-head-sha: ${{ steps.pr_info.outputs.head_ref }} docs-subfolder: ${{ secrets.DOCS_SUBFOLDER }} comment-body: ${{ github.event.comment.body }} docs-base-branch: ${{ secrets.DOCS_BASE_BRANCH || 'main' }} jira-url: ${{ secrets.JIRA_URL }} jira-username: ${{ secrets.JIRA_USERNAME }} jira-api-token: ${{ secrets.JIRA_API_TOKEN }} google-sa-key: ${{ secrets.GOOGLE_SA_KEY }} max-context-chars: ${{ secrets.MAX_CONTEXT_CHARS }}

2 Configure repository secrets

Settings > Secrets and variables > Actions

Name	Value	Description
MODEL_API_BASE	••••••••••	Base URL for OpenAI-compatible API (e.g., vLLM, Gemini, OpenAI)
MODEL_API_KEY	••••••••••	API key for the model endpoint (optional if no auth required)
MODEL_NAME	••••••••••	Model name to use for inference
DOCS_REPO_URL	••••••••••	Docs repository URL (e.g., https://github.com/org/docs)
GH_PAT	••••••••••	GitHub token with repo + pull_requests:write permissions
DOCS_SUBFOLDER	Optional	Docs subfolder path if docs live in the same repo (e.g., docs)
DOCS_BASE_BRANCH	Optional	Base branch for docs PRs (defaults to main)
JIRA_URL	Optional	Jira instance URL (for [review-feature])
JIRA_USERNAME	Optional	Jira username/email
JIRA_API_TOKEN	Optional	Jira API token
GOOGLE_SA_KEY	Optional	Google service account key for fetching spec docs
MAX_CONTEXT_CHARS	Optional	Context budget for LLM prompts (default: 400000)

J

PROJ-456 Project: PROJ

Add webhook notification system

Status In Progress Assignee A alice Type Story Priority Medium

Description

Implement a webhook notification system that allows users to subscribe to events and receive HTTP callbacks.

Spec doc: Webhook System Design Doc (Google Docs)

Webhook System Design Doc Google Docs

What

This feature will implement a webhook notification system that allows users to subscribe to events and receive HTTP callbacks. Currently there is no way for external systems to react to events in real time.

Why

Users need to integrate with external services (Slack, PagerDuty, custom dashboards) but currently must poll the API for changes. We need a push-based notification system.

Currently event status can only be checked manually:

Polling the /events endpoint repeatedly
Checking application logs for state changes

How

Add a webhook notification system with the following components:

Add POST /webhooks endpoint for registering webhook subscriptions with a target URL and event filter
Implement HMAC-SHA256 payload signing using a configurable WEBHOOK_SECRET so receivers can verify authenticity
Add exponential backoff retry logic (max 5 attempts) for failed deliveries
Support event types: user.created, user.updated, order.completed
Add a CLI command app webhooks list to show active webhook subscriptions
Add unit tests covering:
- Payload signing verification
- Retry logic with backoff timing
- Endpoint validation and error handling

Delivery should be async and not block the main request. Failed deliveries after all retries should be logged but not raise alerts.

Alternatives

We could use a message queue (RabbitMQ, Kafka) instead of direct HTTP callbacks, but that adds infrastructure complexity for consumers.
We could use WebSockets for real-time events, but not all integrations support persistent connections.

Accept

Reviewer	Date	Accept or Reject

Add webhook notification system #187

Open alice wants to merge 2 commits into main from add-webhooks

Conversation 2

Files changed 3

alice commented 1 hour ago

This PR implements the webhook notification system from PROJ-456. Changes include:

New POST /webhooks endpoint for webhook registration with URL validation
HMAC-SHA256 payload signing using the configurable WEBHOOK_SECRET
Event dispatcher with exponential backoff retry logic
New configuration options for webhook behavior

▼ src/webhooks/handler.py +156 -0

@@ -0,0 +1,42 @@
 +import hmac
 +import hashlib
 +from config.settings import WEBHOOK_SECRET
 +
 +class WebhookHandler:
 +    """Handles webhook registration and payload signing."""
 +
 +    SUPPORTED_EVENTS = ["user.created", "order.completed"]
 +
 +    def register(self, request):
 +        """POST /webhooks — register a new webhook."""
 +        url = request.json["url"]
 +        events = request.json["events"]
 +        return self._create_subscription(url, events)
 +
 +    def sign_payload(self, payload):
 +        """HMAC-SHA256 signing."""
 +        return hmac.new(WEBHOOK_SECRET, payload, hashlib.sha256)

▼ src/webhooks/dispatcher.py +89 -0

@@ -0,0 +1,28 @@
 +import time
 +import requests
 +from config.settings import WEBHOOK_MAX_RETRIES
 +
 +class EventDispatcher:
 +    """Dispatches events to registered webhooks with retry."""
 +
 +    def dispatch(self, event_type, payload, webhook_url):
 +        for attempt in range(WEBHOOK_MAX_RETRIES):
 +            try:
 +                resp = requests.post(webhook_url, json=payload)
 +                resp.raise_for_status()
 +                return True
 +            except requests.RequestException:
 +                wait = 2 ** attempt  # exponential backoff
 +                time.sleep(wait)
 +        return False

▼ config/settings.py +8 -0

@@ -28,6 +28,14 @@ class Settings:
   SESSION_TIMEOUT = 3600
 +
 +  # Webhook settings
 +  WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET")
 +  WEBHOOK_MAX_RETRIES = 5
 +  WEBHOOK_RETRY_BASE_SECONDS = 2
 +  WEBHOOK_TIMEOUT_SECONDS = 30

Write Preview