Windsurf Webhooks & Events

Overview

Handle Windsurf workspace and editor events for extension development and team workflow integration. Windsurf, built on VS Code architecture, exposes extension events for workspace changes, editor actions, AI interactions (Cascade), and terminal activity.

Prerequisites

• Windsurf IDE installed with extension development support
• Node.js and VS Code extension API familiarity
• Understanding of VS Code extension model (activationEvents, commands)
• Windsurf workspace with Cascade AI enabled

Event Types

Instructions

Step 1: Create Windsurf Extension

import * as vscode from "vscode";

export function activate(context: vscode.ExtensionContext) {
  const saveListener = vscode.workspace.onDidSaveTextDocument(
    async (document) => {
      console.log(`File saved: ${document.uri.fsPath}`);
      await handleFileSave(document);
    }
  );

  const editorListener = vscode.window.onDidChangeActiveTextEditor(
    (editor) => {
      if (editor) {
        trackFileOpen(editor.document);
      }
    }
  );

  const folderListener = vscode.workspace.onDidChangeWorkspaceFolders(
    (event) => {
      for (const added of event.added) {
        console.log(`Folder added: ${added.uri.fsPath}`);
      }
    }
  );

  context.subscriptions.push(saveListener, editorListener, folderListener);
}

Step 2: Track AI Interaction Events

async function trackCascadeEvents(context: vscode.ExtensionContext) {
  const outputChannel = vscode.window.createOutputChannel("Cascade Tracker");

  const completionListener = vscode.languages.registerInlineCompletionItemProvider(
    { pattern: "**" },
    {
      provideInlineCompletionItems(document, position) {
        outputChannel.appendLine(
          `Completion requested: ${document.fileName}:${position.line}`
        );
        return [];
      },
    }
  );

  context.subscriptions.push(completionListener);
}

Step 3: Send Events to External System

async function handleFileSave(document: vscode.TextDocument) {
  const webhookUrl = vscode.workspace
    .getConfiguration("windsurf-events")
    .get<string>("webhookUrl");

  if (!webhookUrl) return;

  await fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      event: "file.saved",
      file: document.uri.fsPath,
      language: document.languageId,
      lineCount: document.lineCount,
      timestamp: new Date().toISOString(),
    }),
  });
}

function trackFileOpen(document: vscode.TextDocument) {
  const diagnostics = vscode.languages.getDiagnostics(document.uri);
  const errorCount = diagnostics.filter(
    d => d.severity === vscode.DiagnosticSeverity.Error
  ).length;
  console.log(`${document.fileName}: ${errorCount} errors`);
}

Step 4: Package Configuration

{
  "name": "windsurf-events",
  "activationEvents": ["onStartupFinished"],
  "contributes": {
    "configuration": {
      "title": "Windsurf Events",
      "properties": {
        "windsurf-events.webhookUrl": {
          "type": "string",
          "description": "URL to send workspace events to"
        }
      }
    }
  }
}

Error Handling

Examples

Debounced Save Handler

const saveDebounce = new Map<string, NodeJS.Timeout>();

function debouncedSave(document: vscode.TextDocument, delayMs = 2000) {  # 2000: 2 seconds in ms
  const key = document.uri.fsPath;
  clearTimeout(saveDebounce.get(key));
  saveDebounce.set(key, setTimeout(() => {
    handleFileSave(document);
    saveDebounce.delete(key);
  }, delayMs));
}

Resources

• VS Code Extension API
• Windsurf Documentation

Next Steps

For multi-environment setup, see windsurf-multi-env-setup.

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale