Event-Driven Automation (EDA)

Forge EDA enables webhook-based event routing with user-defined rules. When an external system sends a webhook (GitHub push, Alertmanager alert, PagerDuty incident, etc.), Forge evaluates conditions and automatically launches job templates, workflows, or sends notifications.

Architecture

External System ──POST──> /api/v2/eda_webhooks/<path>/
                              │
                              ├── HMAC signature verification
                              ├── EventLog created (status: received)
                              └── Celery task dispatched
                                      │
                                      ├── Evaluate Jinja2 conditions
                                      ├── If matched: execute actions
                                      │   ├── Launch JobTemplate
                                      │   ├── Launch WorkflowJobTemplate
                                      │   └── Send NotificationTemplate
                                      └── Log results + AuditEvent

Outbound webhooks work in reverse — when a job completes, Forge POSTs a signed JSON payload to configured external URLs.

Models

EventRule

The core model. Maps a webhook endpoint to conditions and actions.

EventLog

Immutable log of every received webhook and its evaluation outcome.

OutboundWebhook

Push job status changes to external systems.

API Endpoints

Event Rules

Event Logs

Outbound Webhooks

Public Receiver

Conditions (Jinja2)

Conditions are Jinja2 expressions evaluated against the webhook payload. All conditions must match (AND logic). Empty conditions = always match.

Context variables:

Examples:

# GitHub: only PR opened events
- jinja2_expression: "event.action == 'opened'"
  description: "Pull request opened"

# Alertmanager: only firing alerts for production
- jinja2_expression: "event.status == 'firing'"
  description: "Alert is firing"
- jinja2_expression: "'production' in event.commonLabels.environment"
  description: "Production environment"

# Generic: check for specific field value
- jinja2_expression: "event.severity == 'critical'"
  description: "Critical severity only"

Actions

Injected extra variables (available in playbooks):

Signature Verification

X-Forge-Signature format: sha256=<hex_digest>

To sign a payload with the webhook key:

echo -n '{"event":"test"}' | openssl dgst -sha256 -hmac 'YOUR_WEBHOOK_KEY'

Security

• HMAC verification on all incoming webhooks
• Jinja2 sandboxing via ImmutableSandboxedEnvironment (no file access, no dangerous calls)
• Rate limiting via throttle_seconds per rule
• Payload size limit: 1MB max
• Deduplication: Duplicate event_guid values are rejected
• RBAC: Rules scoped to organizations, org admins manage rules
• Audit trail: Every rule firing creates an AuditEvent

Quick Start

1. Create an Event Rule

curl -X POST https://forge.example.com/api/v2/event_rules/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy on GitHub push to main",
    "organization": 1,
    "source_type": "webhook_github",
    "webhook_path": "github-deploy",
    "conditions": [
      {"jinja2_expression": "event.ref == \"refs/heads/main\"", "description": "Push to main"}
    ],
    "actions": [
      {"action_type": "launch_job_template", "target_id": 5, "description": "Run deploy playbook"}
    ]
  }'

2. Copy the webhook URL and key

From the response, note the webhook_url and retrieve the key:

curl https://forge.example.com/api/v2/event_rules/1/webhook_key/ \
  -H "Authorization: Bearer <token>"

3. Configure GitHub webhook

In your GitHub repository Settings > Webhooks: - Payload URL: https://forge.example.com/api/v2/eda_webhooks/github-deploy/ - Content type: application/json - Secret: The webhook key from step 2 - Events: Push events

4. Test with dry-run

curl -X POST https://forge.example.com/api/v2/event_rules/1/test/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {"ref": "refs/heads/main", "action": "push"},
    "headers": {}
  }'

Frontend

The EDA UI is available in the Automation sidebar section:

• Event Rules (/event_rules) — Create, edit, enable/disable rules
• Event Logs (/event_logs) — View incoming webhooks and evaluation results
• Outbound Webhooks (/outbound_webhooks) — Configure job status push notifications

Each Event Rule detail page shows: - Webhook URL (copy-to-clipboard) - Webhook key (show/rotate) - Condition and action configuration - Recent event logs with status badges - Dry-run test capability