[Phase 6.8] Webhook Endpoints

Mark commented

2026-04-02 20:54:59 +00:00

Owner

Overview

Webhook endpoints for receiving events from external systems.

Problem Statement

Current mesh can only receive intents via API. Cannot:

Receive GitHub webhooks (push, PR, issues)
Receive CI/CD events (build complete, test failed)
Integrate with external tools (Jira, Linear, PagerDuty)
React to external events automatically

Proposed Solution

6.8.1: Webhook Endpoints

endpoints:
  POST /webhooks/github:
    headers: {X-GitHub-Event, X-Hub-Signature}
    body: GitHub webhook payload
    returns: {accepted: true, intent_id}
    
  POST /webhooks/custom/<name>:
    body: Custom webhook payload
    returns: {accepted: true, intent_id}

6.8.2: Webhook Handler Registry

class WebhookHandler:
    """Process incoming webhooks, emit intents."""
    
    def register(self, source: str, handler: Callable):
        """Register handler for webhook source"""
        
    def handle(self, source: str, headers: dict, body: dict) -> IntentID:
        """Process webhook, emit intent"""
        
    def verify_signature(self, source: str, signature: str, body: str) -> bool:
        """Verify webhook authenticity"""

6.8.3: GitHub Webhook Handler

def handle_github_webhook(event_type: str, payload: dict) -> Intent:
    """Convert GitHub event to mesh intent."""
    
    if event_type == "push":
        return {
            "intent_type": "process_push",
            "payload": {
                "repo": payload["repository"]["full_name"],
                "branch": payload["ref"],
                "commits": [c["id"] for c in payload["commits"]]
            }
        }
    elif event_type == "pull_request":
        return {
            "intent_type": "review_pr",
            "payload": {
                "repo": payload["repository"]["full_name"],
                "pr_number": payload["number"],
                "action": payload["action"]
            }
        }

6.8.4: Webhook Configuration

# config/webhooks.yaml
webhooks:
  github:
    secret: ${GITHUB_WEBHOOK_SECRET}
    events:
      - push
      - pull_request
      - issues
    handlers:
      push: handle_push
      pull_request: handle_pr
      
  custom:
    - name: deploy_complete
      intent_type: post_deploy
      secret: ${CUSTOM_WEBHOOK_SECRET}

Deliverables

Webhook endpoint in runtime/http_entrypoint.py
runtime/webhook_handler.py - Handler registry
GitHub webhook handler
Signature verification
Configuration for webhook sources
Unit tests
Integration tests

Dependencies

None (standalone)

Estimated Duration

1 week

Success Criteria

Webhook endpoint receives POST requests
GitHub webhooks processed to intents
Signatures verified for security
Custom webhooks supported
Webhooks trigger mesh actions

Parent: #69 (Phase 6 Meta)

## Overview Webhook endpoints for receiving events from external systems. ## Problem Statement Current mesh can only receive intents via API. Cannot: - Receive GitHub webhooks (push, PR, issues) - Receive CI/CD events (build complete, test failed) - Integrate with external tools (Jira, Linear, PagerDuty) - React to external events automatically ## Proposed Solution ### 6.8.1: Webhook Endpoints ```yaml endpoints: POST /webhooks/github: headers: {X-GitHub-Event, X-Hub-Signature} body: GitHub webhook payload returns: {accepted: true, intent_id} POST /webhooks/custom/<name>: body: Custom webhook payload returns: {accepted: true, intent_id} ``` ### 6.8.2: Webhook Handler Registry ```python class WebhookHandler: """Process incoming webhooks, emit intents.""" def register(self, source: str, handler: Callable): """Register handler for webhook source""" def handle(self, source: str, headers: dict, body: dict) -> IntentID: """Process webhook, emit intent""" def verify_signature(self, source: str, signature: str, body: str) -> bool: """Verify webhook authenticity""" ``` ### 6.8.3: GitHub Webhook Handler ```python def handle_github_webhook(event_type: str, payload: dict) -> Intent: """Convert GitHub event to mesh intent.""" if event_type == "push": return { "intent_type": "process_push", "payload": { "repo": payload["repository"]["full_name"], "branch": payload["ref"], "commits": [c["id"] for c in payload["commits"]] } } elif event_type == "pull_request": return { "intent_type": "review_pr", "payload": { "repo": payload["repository"]["full_name"], "pr_number": payload["number"], "action": payload["action"] } } ``` ### 6.8.4: Webhook Configuration ```yaml # config/webhooks.yaml webhooks: github: secret: ${GITHUB_WEBHOOK_SECRET} events: - push - pull_request - issues handlers: push: handle_push pull_request: handle_pr custom: - name: deploy_complete intent_type: post_deploy secret: ${CUSTOM_WEBHOOK_SECRET} ``` ## Deliverables - [ ] Webhook endpoint in `runtime/http_entrypoint.py` - [ ] `runtime/webhook_handler.py` - Handler registry - [ ] GitHub webhook handler - [ ] Signature verification - [ ] Configuration for webhook sources - [ ] Unit tests - [ ] Integration tests ## Dependencies - None (standalone) ## Estimated Duration 1 week ## Success Criteria - [ ] Webhook endpoint receives POST requests - [ ] GitHub webhooks processed to intents - [ ] Signatures verified for security - [ ] Custom webhooks supported - [ ] Webhooks trigger mesh actions ## Related - Parent: #69 (Phase 6 Meta)