M14: add n8n execution health telemetry

backend/app/api/routers/integrations.py

@@ -15,6 +15,8 @@ from app.core.errors import AppError
 from app.models.audit import AuditEvent
 from app.models.outbox import OutboxEvent
 from app.schemas import (
+    N8nHeartbeatIn,
+    N8nHeartbeatResult,
     ProcedureDocumentOut,
     ProcedureListOut,
     ProcedureSyncResultIn,
@@ -30,6 +32,58 @@ from app.services.knowledge.procedures import iter_procedure_documents
 router = APIRouter(prefix="/api/v1/integrations/n8n", tags=["integrations"])
 settings = get_settings()
 
+_CANONICAL_WORKFLOW_NAMES = frozenset(
+    {
+        "Fleet Ops — Vehicle Return Orchestration",
+        "Fleet Ops — Scheduled Data Quality Scan",
+        "Fleet Ops — RAGcore Procedure Sync",
+        "Fleet Ops — Workflow Error Handler",
+    }
+)
+
+
+@router.post("/heartbeat", response_model=N8nHeartbeatResult)
+def workflow_heartbeat(
+    body: N8nHeartbeatIn,
+    service_token: str = Header(..., alias="X-Service-Token"),
+    db: Session = Depends(get_db),
+) -> N8nHeartbeatResult:
+    """Authenticated, idempotent execution evidence from a canonical n8n workflow."""
+    if service_token != settings.n8n_callback_token:
+        raise AppError("UNAUTHORIZED_SERVICE", "Invalid service token.", status_code=401)
+    if body.workflow_name not in _CANONICAL_WORKFLOW_NAMES:
+        raise AppError("UNKNOWN_WORKFLOW", "Unknown Fleet Ops workflow.", status_code=422)
+    already_recorded = (
+        db.scalar(
+            select(AuditEvent.id).where(
+                AuditEvent.action == "n8n_workflow_heartbeat",
+                AuditEvent.metadata_json["execution_id"].astext == body.execution_id,
+                AuditEvent.after_json["status"].astext == body.status,
+            )
+        )
+        is not None
+    )
+    if not already_recorded:
+        record_audit_event(
+            db,
+            actor_type="service",
+            actor_label="n8n workflow heartbeat",
+            action="n8n_workflow_heartbeat",
+            entity_type="automation",
+            after={
+                "workflow_id": body.workflow_id,
+                "workflow_name": body.workflow_name,
+                "status": body.status,
+            },
+            metadata={"execution_id": body.execution_id},
+        )
+        db.commit()
+    return N8nHeartbeatResult(
+        status="already_registered" if already_recorded else "registered",
+        execution_id=body.execution_id,
+        occurred_at=datetime.now(UTC),
+    )
+
 
 @router.post("/return-callback")
 def return_callback(