Webhooks for host activities

[noahtalerman]

Goal

User story
As an IT admin,
I want to send webhooks for every host activity
so that I can trigger automations or send activity to my SIEM for historical tracking/graphing.

Changes

Product

• UI changes: Figma
• CLI (fleetctl) usage changes: No changes
• YAML changes:
  • PR to GitOps docs adding host_ activities_webhook object to webhook​_settings for fleet config: Docs: per-fleet host activities webhook and enriched activity details #50488
• REST API changes:
  • PR to Update fleet endpoint adding host_ activities_webhook object to webhook​_settings: Docs: per-fleet host activities webhook and enriched activity details #50488
  • Add host_id to details field for all host-specific activities (aka anything that shows up in the host activity feed)
  • Add profile_uuid to details field for install and remove profile activities
• Fleet's agent (fleetd) changes: No changes
• Fleet server configuration changes: No changes
• Exposed, public API endpoint changes: No changes
• fleetdm.com changes: No changes
• GitOps mode UI changes: No changes
• GitOps generation changes: fleetctl generate-gitops includes webhook_settings.host_activities_webhook for fleets and “No fleet” so the setting round-trips
• Activity changes: No changes
• Permissions changes: No changes
• Changes to paid features or tiers: Fleet Premium
• My device and fleetdm.com/better changes: No changes
• Usage statistics: No changes
• Other reference documentation changes: No changes
• First draft of test plan added
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed

Engineering

Sub-tasks: #50217 (backend: settings + webhook firing + GitOps), #50218 (backend: activity details enrichment), #50219 (frontend: gear menu + modal), #50220 (docs + engineering QA). Spec: 40493-spec-host-activity-webhooks.md (with @nulmete).

• Test plan is finalized
• Contributor API changes: docs/Contributing/reference/api-for-contributors.md — add webhook_settings (incl. host_activities_webhook) to the Apply fleet spec parameter table; docs/Contributing/reference/audit-logs.md — new host_ids detail field on the 8 policy-automation activities, host_id on Windows mdm_enrolled, profile_uuid on resent-profile activities (Host activity webhooks: activity details enrichment (host_ids for policy automations, host_id for Windows mdm_enrolled, profile_uuid for resent profiles) #50218, Host activity webhooks: documentation #50220)
• Feature guide changes: small update to the existing automations documentation to cover per-fleet host activity automations (Host activity webhooks: documentation #50220)
• Database schema migrations: none — fleet webhook settings serialize into the teams.config JSON column; “No fleet” uses the existing default_team_config_json table
• Load testing: not required — cost per host-linked activity is one hosts-lite lookup + one team-config read + an async POST on a path that already writes to the DB
• Pre-QA load test: not needed — no measurable change to Fleet's load profile
• Load testing/osquery-perf improvements: none
• This is a premium only feature: Yes — backend: fleet endpoints are enterprise-only and the firing path checks the license; frontend: menu item disabled with a Premium tooltip on Free

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

• Requires testing in a hosted environment: No — a public webhook receiver (e.g. webhook.site) is enough
• Requires load testing: No
• Risk level: Low
• Risk description: watch for log spew from failing webhook destinations (one error line after retries) and 429 backoff goroutines (bounded at 30 minutes) — same behavior as the existing global activities webhook

Test plan

Make sure to go through the list and consider all events that might be related to this story, so we catch edge cases earlier.

• Premium, global admin: Hosts page → select a fleet → gear menu → Activity automations → enable + webhook.site URL → Save. Run a script on a host in that fleet → one POST arrives with type: "ran_script" and details.host_id; payload format matches the global activities webhook.
• Repeat for “No fleet” (fleet 0).
• Scoping: activity for a host in fleet A does not reach fleet B's webhook; global-only activities (e.g. live query, ran_script_batch) never fire the fleet webhook; with the global webhook also enabled, both fire for host activities.
• Settings API: PATCH /fleets/{id} with webhook_settings.host_activities_webhook round-trips (Get/List fleets); enabling with an empty or non-http(s) URL returns 422; a PATCH sending webhook_settings without host_activities_webhook (e.g. policy automations flow) preserves the stored value.
• Details enrichment: failing-policy automation run → ran_automation_webhook details include host_ids; Windows MDM enrollment → mdm_enrolled has host_id and appears on the host feed; resend a profile → resent_configuration_profile details include profile_uuid.
• GitOps: team YAML and “No fleet” YAML apply the setting; fleetctl generate-gitops round-trips it; GitOps mode disables the modal inputs.
• Roles: fleet admin of the selected fleet can configure; maintainers/observers cannot; “All fleets” shows the option disabled with a tooltip.
• Fleet Free: option disabled with Premium tooltip; no webhook fires even if config exists in the DB.

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan.
2. QA: Added comment to user story confirming successful completion of test plan.

[sharon-fdm]

@lucasmrod, I'm estimating to S due to haveing done that several times in the past. Tell me if you think otherwise.