Implement Windsurf webhook signature validation and event handling.
Use when setting up webhook endpoints, implementing signature verification,
or handling Windsurf event notifications securely.
Trigger with phrases like "windsurf webhook", "windsurf events",
"windsurf webhook signature", "handle windsurf events", "windsurf notifications".
Windsurf is built on VS Code and supports the full VS Code Extension API. Build custom extensions to track workspace events, integrate with external tools, and extend Cascade's capabilities. This skill covers extension development specific to the Windsurf environment.
Prerequisites
Node.js 18+ and npm
VS Code Extension API familiarity
yo and generator-code for scaffolding
Windsurf IDE for testing
Instructions
Step 1: Scaffold Extension
# Install scaffolding tools
npm install -g yo generator-code
# Generate extension
yo code
# Select: New Extension (TypeScript)
# Name: my-windsurf-extension
Step 2: Track Workspace Events
// src/extension.ts
import * as vscode from "vscode";
export function activate(context: vscode.ExtensionContext) {
console.log("Extension active in Windsurf");
// Track file saves
const saveListener = vscode.workspace.onDidSaveTextDocument(
async (document) => {
const diagnostics = vscode.languages.getDiagnostics(document.uri);
const errors = diagnostics.filter(
(d) => d.severity === vscode.DiagnosticSeverity.Error
);
if (errors.length > 0) {
vscode.window.showWarningMessage(
`${document.fileName}: ${errors.length} error(s) after save`
);
}
}
);
// Track active editor changes
const editorListener = vscode.window.onDidChangeActiveTextEditor(
(editor) => {
if (editor) {
const lang = editor.document.languageId;
const lines = editor.document.lineCount;
console.log(`Opened: ${editor.document.fileName} (${lang}, ${lines} lines)`);
}
}
);
// Track terminal output
const terminalListener = vscode.window.onDidWriteTerminalData((event) => {
// Can monitor for specific patterns (errors, warnings)
if (event.data.includes("ERROR") || event.data.includes("FAIL")) {
vscode.window.showWarningMessage("Error detected in terminal output");
}
});
context.subscriptions.push(saveListener, editorListener, terminalListener);
}
# Build
npm run compile
# or: npm run build
# Package as .vsix
npx vsce package
# Install in Windsurf
windsurf --install-extension windsurf-events-1.0.0.vsix
# Or publish to marketplace
npx vsce publish
Step 6: Test in Windsurf
1. Open Extension Development Host: F5 in Windsurf
2. A new Windsurf window opens with extension loaded
3. Open a file, save it, trigger events
4. Check Output panel > "Windsurf Events" channel
5. Verify webhook delivery (use https://webhook.site for testing)
Error Handling
Issue
Cause
Solution
Extension not activating
Wrong activationEvents
Use onStartupFinished for always-on
Webhook fails
Network/URL issue
Queue locally, retry with backoff
High CPU usage
Too many listeners
Debounce frequent events (saves, edits)
API incompatibility
Windsurf vs VS Code version
Pin engines.vscode version
vsce package fails
Missing fields
Add publisher, repository, license
Examples
Team Analytics Extension
// Track AI acceptance rate per developer
vscode.languages.registerInlineCompletionItemProvider(
{ pattern: "**" },
{
provideInlineCompletionItems(document, position) {
// Log completion requests (don't interfere with Supercomplete)
console.log(`Completion at ${document.fileName}:${position.line}`);
return []; // Return empty -- let Windsurf handle completions
}
}
);
Quick Test Webhook
# Start a test webhook receiver
npx -y webhook-relay -p 3456
# Configure extension: windsurf-events.webhookUrl = "http://localhost:3456"
