Webhooks & Events
Relevant source files
The following files were used as context for generating this wiki page:
The Webhooks & Events system in FixOps provides a bidirectional communication layer between the FixOps decision engine and external enterprise tools. It facilitates real-time incident response, automated remediation, and compliance tracking by receiving inbound events from third-party platforms and dispatching outbound events through a managed outbox pattern.
This system is essential for maintaining synchronization between security findings and issue trackers like Jira, CI/CD pipelines, and communication platforms like Slack. It ensures that every decision made within the FixOps pipeline can trigger immediate downstream actions and that updates in external tools are reflected back into the FixOps evidence lake.
Sources: CLI_API_INVENTORY.md, web/apps/integrations/app/page.tsx:81-100
Architecture and Data Flow
The architecture consists of three primary components: Inbound Webhook Receivers, the Outbox Management system, and Event Mappings. The system is designed to handle asynchronous communication, ensuring that FixOps remains resilient even if external connectors are temporarily unavailable.
Event Processing Flow
The following diagram illustrates the flow of data from an external event trigger to the execution of an automated playbook response.
This flow ensures that inbound signals (like a ticket being closed in Jira) can be reconciled with internal FixOps states, and internal decisions can be pushed out to external systems.
Sources: CLI_API_INVENTORY.md, samples/api-examples/demo-scenarios/automation/yaml-playbooks.json:30-60
Inbound Webhook Receivers
FixOps provides specialized endpoints to receive events from common enterprise DevOps and ITSM tools. These receivers parse incoming payloads and translate them into canonical FixOps events.
| Provider | Purpose | Status |
|---|---|---|
| Jira | Syncs issue status changes and comments back to FixOps. | Working |
| ServiceNow | Receives incident updates and work note additions. | Working |
| GitLab | Tracks merge requests and issue updates. | Working |
| Azure DevOps | Monitors work item changes and completions. | Working |
Sources: CLI_API_INVENTORY.md
Supported Inbound Payloads
Inbound webhooks are expected to follow specific structures depending on the provider. For example, the Jira receiver processes jira:issue_updated events, while ServiceNow requires event_type and sys_id fields.
Sources: tests/e2e/comprehensive_e2e_test.py:1150-1175
Outbox Management
The Outbox system acts as a reliable messaging queue for outbound operations. Instead of making synchronous calls to external APIs, FixOps records intended actions in an outbox, which are then executed by background workers or manual triggers.
Outbox Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/webhooks/outbox | GET | List all queued outbox items. |
/api/v1/webhooks/outbox/{id} | GET | Retrieve detailed information for a specific outbox item. |
/api/v1/webhooks/outbox/{id}/execute | POST | Manually trigger the execution of a specific item via its connector. |
/api/v1/webhooks/outbox/process-pending | POST | Batch process all items currently in a "pending" status. |
Sources: CLI_API_INVENTORY.md
Sequence of Outbound Execution
The outbox pattern ensures durability and provides an audit trail for all external communications.
Event Types and Playbooks
Webhooks are often driven by the Playbook Engine, which evaluates conditions and triggers specific actions based on event types.
Common Internal Events
FixOps generates several internal events that can be subscribed to via custom webhooks or playbooks:
finding.created: A new security vulnerability is detected.finding.updated: An existing finding changes status or severity.ssvc.decision: A final ALLOW/BLOCK/DEFER decision is reached.compliance.gap: A control failure is identified.evidence.created: A new evidence bundle is materialized and signed.
Sources: web/apps/integrations/app/page.tsx:81-100
Automated Playbook Example
Playbooks define how FixOps should respond to these events using YAML definitions.
name: Critical Vulnerability Response
trigger:
type: vulnerability_detected
conditions:
severity: critical
cvss_score: ">=9.0"
steps:
- name: Create P1 Jira Ticket
action: create_jira_ticket
params:
project: SEC
priority: P1
- name: Send Slack Alert
action: send_slack_notification
params:
channel: "#security-alerts"
Sources: samples/api-examples/demo-scenarios/automation/yaml-playbooks.json:30-65
UI and Configuration
The Integrations UI allows users to manage active webhooks and configure new connections. Users can select which events trigger a specific webhook URL and track the success rate of past deliveries.
Configuration Options
When adding a webhook, the following parameters are required:
- Webhook Name: A descriptive label for the integration.
- Webhook URL: The destination address for the POST request.
- Events: A selection of event types (e.g.,
finding.created,ssvc.decision) that will trigger the webhook.
Sources: web/apps/integrations/app/page.tsx:280-320
Summary
The Webhooks & Events system provides the necessary glue for FixOps to function within a modern enterprise ecosystem. By utilizing an inbound receiver architecture and an outbound outbox pattern, it ensures that security decisions are actionable and that the state of vulnerabilities is consistently synchronized across all connected platforms. This closed-loop communication enables features like "drift detection," where FixOps identifies if a ticket status in Jira no longer matches the internal security posture.
Sources: CLI_API_INVENTORY.md, web/apps/integrations/app/page.tsx:1-50