Webhooks & Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Webhooks and integrations in Fleet serve as the primary mechanism for connecting device management workflows with external enterprise systems. This system facilitates automated alerting, ticket generation in platforms like Jira and Zendesk, and real-time data streaming to security operations tools. By leveraging these integrations, organizations can automate responses to failing policies, host status changes, and newly discovered vulnerabilities.
The architecture supports both organization-level global settings and fleet-specific configurations, allowing for granular control over how data is dispatched to external endpoints. The integration layer is designed to bridge the gap between Fleet's live osquery data and the broader IT ecosystem, ensuring that critical security events are surfaced in the tools already used by security and IT teams.
Sources: tools/fleet-slackbot/system-prompt.js:237-258, handbook/product-design/README.md:27-31
Integration Architecture
Fleet's integration architecture is defined through YAML configurations that specify how the server interacts with third-party services. The system supports a variety of service types, primarily focusing on project management, ticketing, and messaging platforms.
Core Integration Types
The system supports several key integration categories as defined in the global default.yml configuration:
| Service | Primary Purpose | Key Configuration Parameters |
|---|---|---|
| Jira | Ticket creation for policies/vulnerabilities | url, username, api_token, project_key |
| Zendesk | Automated support ticket generation | url, username, api_token, group_id |
| Google Calendar | Scheduling/Visibility for device events | api_key_json, domain |
| Webhooks | Real-time HTTP callbacks | destination_url, host_batch_size, interval |
Sources: tools/fleet-slackbot/system-prompt.js:237-258, tools/README.md:95-108
Configuration Data Flow
Integrations are defined at two levels: Global (Org Settings) and Fleet-specific. The global configuration acts as a baseline, while fleet-specific files (e.g., workstations.yml) can define specific webhook behaviors for targeted groups of hosts.
The diagram illustrates how configuration files and internal event triggers converge in the Fleet Server to drive external integration actions.
Webhook Operations
Webhooks are the most flexible integration point in Fleet, allowing for custom HTTP POST requests to be sent to external endpoints when specific criteria are met.
Webhook Event Types
Fleet categorizes webhook triggers into three functional areas:
- Failing Policies Webhook: Triggered when hosts fail specific osquery-based policies. Configuration includes
policy_idsto monitor andhost_batch_sizeto control the volume of data sent per request. - Host Status Webhook: Monitors the health of the fleet based on
days_countandhost_percentagethresholds, alerting when a significant portion of the fleet becomes inactive. - Vulnerabilities Webhook: Dispatched when new vulnerabilities (CVEs) are detected on hosts, facilitating immediate security response.
Sources: tools/fleet-slackbot/system-prompt.js:145-152, tools/fleet-slackbot/system-prompt.js:252-258
Integration Testing Utilities
The project provides several tools for validating integration functionality during development and operations:
- Webhook Tester: A utility (
tools/webhook) to listen for and display incoming webhook payloads on a specific port. - Jira Integration Tool: (
tools/jira-integration) Used to simulate ticket creation for CVEs and host counts. - Zendesk Integration Tool: (
tools/zendesk-integration) Simulates Zendesk ticket generation with specific CVE data.
Sources: tools/README.md:58-62, tools/README.md:95-108
Automated Ticket Management
Ticketing integrations (Jira and Zendesk) are often tied to failing policies to ensure remediation is tracked.
Data Mapping for Tickets
When a policy fails or a vulnerability is detected, Fleet maps internal data to the external service's schema. This includes:
- Contextual Data: Host details, platform information, and specific policy results.
- Remediation Instructions: The
resolutionfield defined in policy YAML files is often passed to the ticket to guide IT staff.
Sources: tools/fleet-slackbot/system-prompt.js:183-188, tools/README.md:95-108
Sequence of events from a host-side policy failure to the creation of a Jira ticket.
Sources: tools/fleet-slackbot/system-prompt.js:145-152, tools/README.md:95-108
Interactive Integrations (Slackbot)
Fleet includes an AI-powered Slackbot that integrates with the Fleet API and GitOps workflows to provide an interactive management interface.
Bot Capabilities
The Slackbot acts as a bridge between user chat and Fleet operations:
- Information Retrieval: Uses Fleet tools to answer questions about endpoint counts, compliance, and vulnerabilities.
- Configuration Changes: Proposes GitOps YAML changes (e.g., adding software or changing policies) by submitting GitHub pull requests.
Sources: tools/fleet-slackbot/system-prompt.js:1-12, tools/fleet-slackbot/system-prompt.js:23-35
Implementation Logic
The bot uses a system prompt to decide between "Information Retrieval" (plain-text answers) and "Configuration Changes" (JSON-formatted PR proposals). It utilizes specific Fleet tools such as get_endpoints, get_host_policies, and run_live_query to interact with the environment.
Sources: tools/fleet-slackbot/system-prompt.js:15-22, tools/fleet-slackbot/system-prompt.js:37-55
Summary of Integration Parameters
The following table summarizes the parameters available for webhook and integration configuration within the YAML-based management system.
| Parameter | Scope | Description |
|---|---|---|
destination_url | Webhook | The target HTTP(S) endpoint for the POST request. |
host_batch_size | Webhook | Maximum number of host records included in a single webhook dispatch. |
project_key | Jira | The Jira project where issues should be created. |
group_id | Zendesk | The specific Zendesk group ID assigned to new tickets. |
interval | Global | Frequency at which Fleet checks for and dispatches webhook events (e.g., "24h"). |
Sources: tools/fleet-slackbot/system-prompt.js:237-258, handbook/ceo/README.md:27-31
Webhooks and integrations form a critical automated feedback loop within Fleet, transforming raw host telemetry into actionable tasks within the broader organization's technical ecosystem. By combining real-time HTTP callbacks with deep ticketing service support, Fleet ensures that security and compliance data is never siloed.