Obsidian Webhooks & Events Skill

Obsidian Webhooks & Events

Overview

Complete guide to Obsidian's event system: vault events (create, modify, delete, rename), workspace events (layout, leaf changes, editor state), metadataCache events, DOM events, custom EventRef patterns, and periodic tasks. Every event registration uses this.registerEvent() for automatic cleanup on plugin unload.

Prerequisites

Working Obsidian plugin with onload() / onunload() lifecycle
Understanding of TypeScript event handler signatures
Familiarity with Obsidian's TFile, TFolder, and WorkspaceLeaf types

Instructions

Step 1: Vault Events — File Lifecycle

Vault events fire when files and folders are created, modified, deleted, or renamed.

import { Plugin, TFile, TFolder, TAbstractFile } from 'obsidian';

export default class EventPlugin extends Plugin {
  async onload() {
    // File created
    this.registerEvent(
      this.app.vault.on('create', (file: TAbstractFile) => {
        if (file instanceof TFile) {
          console.log('New file:', file.path);
          this.onFileCreated(file);
        }
        if (file instanceof TFolder) {
          console.log('New folder:', file.path);
        }
      })
    );

    // File content modified (fires on save and on every sync update)
    this.registerEvent(
      this.app.vault.on('modify', (file: TAbstractFile) => {
        if (file instanceof TFile) {
          this.onFileModified(file);
        }
      })
    );

    // File deleted
    this.registerEvent(
      this.app.vault.on('delete', (file: TAbstractFile) => {
        if (file instanceof TFile) {
          this.removeFromIndex(file.path);
        }
      })
    );

    // File renamed or moved (includes folder moves)
    this.registerEvent(
      this.app.vault.on('rename', (file: TAbstractFile, oldPath: string) => {
        if (file instanceof TFile) {
          this.updatePathReferences(oldPath, file.path);
        }
      })
    );
  }
}

Note: modify fires on every keystroke during live editing in some configurations. Always debounce if your handler does non-trivial work (see obsidian-rate-limits).

Step 2: Workspace Events — UI State Changes

Workspace events track what the user is looking at and how the UI layout changes.

async onload() {
  // Active file changed (user clicked a different tab/pane)
  this.registerEvent(
    this.app.workspace.on('active-leaf-change', (leaf) => {
      if (leaf) {
        const view = leaf.view;
        if (view.getViewType() === 'markdown') {
          const file = (view as any).file as TFile;
          if (file) {
            this.onActiveFileChanged(file);
          }
        }
      }
    })
  );

  // File opened in any pane (fires even if already active)
  this.registerEvent(
    this.app.workspace.on('file-open', (file: TFile | null) => {
      if (file) {
        this.trackRecentFile(file);
      }
    })
  );

  // Layout changed (panes split, closed, rearranged)
  this.registerEvent(
    this.app.workspace.on('layout-change', () => {
      this.updateSidebarState();
    })
  );

  // Editor changed (cursor moved, selection changed, content edited)
  this.registerEvent(
    this.app.workspace.on('editor-change', (editor, info) => {
      // info is MarkdownView — gives you the file context
      const cursor = editor.getCursor();
      this.onCursorMoved(cursor.line, cursor.ch);
    })
  );

  // Window/pane resized
  this.registerEvent(
    this.app.workspace.on('resize', () => {
      this.adjustCustomViews();
    })
  );

  // Wait for layout to be fully initialized before accessing panes
  this.app.workspace.onLayoutReady(() => {
    this.initializeWithCurrentState();
  });
}

Step 3: MetadataCache Events — Content Indexing

The metadataCache parses frontmatter, links, tags, and headings in the background. These events fire when parsing completes.

async onload() {
  // Single file's metadata changed (fires after modify, once parsing is done)
  this.registerEvent(
    this.app.metadataCache.on('changed', (file: TFile, data: string, cache: CachedMetadata) => {
      // cache contains parsed frontmatter, links, tags, headings
      const tags = cache.tags?.map(t => t.tag) ?? [];
      const links = cache.links?.map(l => l.link) ?? [];
      this.updateFileIndex(file.path, { tags, links });
    })
  );

  // All files in vault have been indexed (fires once after startup)
  this.registerEvent(
    this.app.metadataCache.on('resolved', () => {
      console.log('Metadata cache fully resolved — safe to query all files');
      this.buildFullIndex();
    })
  );
}

private buildFullIndex() {
  const files = this.app.vault.getMarkdownFiles();
  for (const file of files) {
    const cache = this.app.metadataCache.getFileCache(file);
    if (cache) {
      this.updateFileIndex(file.path, {
        tags: cache.tags?.map(t => t.tag) ?? [],
        links: cache.links?.map(l => l.link) ?? [],
        headings: cache.headings?.map(h => h.heading) ?? [],
        frontmatter: cache.frontmatter,
      });
    }
  }
}

The resolved event is critical for plugins that build indexes — querying metadataCache before it fires returns incomplete data.

Step 4: DOM Events with registerDomEvent

For custom UI elements, use registerDomEvent instead of raw addEventListener. Obsidian auto-removes these on plugin unload.

async onload() {
  // Register click handler on a custom element
  const button = this.addStatusBarItem();
  button.setText('Click me');

  this.registerDomEvent(button, 'click', (evt: MouseEvent) => {
    new Notice('Status bar clicked!');
  });

  // Listen for keyboard shortcuts on the document
  this.registerDomEvent(document, 'keydown', (evt: KeyboardEvent) => {
    if (evt.ctrlKey && evt.key === 'q') {
      this.toggleFeature();
    }
  });

  // Drag and drop on a custom view
  const dropZone = createEl('div', { cls: 'my-drop-zone' });
  this.registerDomEvent(dropZone, 'dragover', (evt: DragEvent) => {
    evt.preventDefault();
    dropZone.addClass('drag-active');
  });

  this.registerDomEvent(dropZone, 'drop', async (evt: DragEvent) => {
    evt.preventDefault();
    dropZone.removeClass('drag-active');
    const files = evt.dataTransfer?.files;
    if (files?.length) {
      await this.handleDroppedFiles(files);
    }
  });
}

Step 5: Periodic Tasks with registerInterval

Use registerInterval for timers — they auto-clear on unload. Never use raw setInterval.

async onload() {
  // Auto-save draft every 30 seconds
  this.registerInterval(
    window.setInterval(() => {
      this.autoSaveDraft();
    }, 30_000)
  );

  // Refresh external data every 5 minutes
  this.registerInterval(
    window.setInterval(() => {
      this.refreshExternalData();
    }, 5 * 60_000)
  );
}

private draftSaving = false;

private async autoSaveDraft() {
  // Overlap guard — skip if previous save is still running
  if (this.draftSaving) return;
  this.draftSaving = true;
  try {
    const view = this.app.workspace.getActiveViewOfType(MarkdownView);
    if (view?.file) {
      const content = view.editor.getValue();
      await this.saveDraft(view.file.path, content);
    }
  } finally {
    this.draftSaving = false;
  }
}

Step 6: Custom Event Bus for Plugin-Internal Communication

For complex plugins with multiple views or components, create an internal event bus.

import { Events } from 'obsidian';

// Create a typed event bus
class PluginEventBus extends Events {
  // Type-safe event methods
  onIndexUpdated(callback: (paths: string[]) => void): EventRef {
    return this.on('index-updated', callback);
  }

  triggerIndexUpdated(paths: string[]) {
    this.trigger('index-updated', paths);
  }

  onSettingsChanged(callback: (settings: PluginSettings) => void): EventRef {
    return this.on('settings-changed', callback);
  }

  triggerSettingsChanged(settings: PluginSettings) {
    this.trigger('settings-changed', settings);
  }
}

// Usage in plugin
class MyPlugin extends Plugin {
  bus = new PluginEventBus();

  async onload() {
    // Views subscribe to events
    this.registerEvent(
      this.bus.onIndexUpdated((paths) => {
        this.sidebarView?.refresh(paths);
      })
    );

    // Something triggers the event
    this.registerEvent(
      this.app.vault.on('modify', async (file) => {
        if (file instanceof TFile) {
          await this.reindex(file);
          this.bus.triggerIndexUpdated([file.path]);
        }
      })
    );
  }
}

Obsidian's Events class is the same base class used by Vault, Workspace, and MetadataCache. Using it for your own bus gives you a consistent pattern with on/off/trigger.

Output

Vault event handlers for file create, modify, delete, rename
Workspace event handlers for active leaf, file open, editor changes, layout
MetadataCache handlers for content parsing and full-vault resolution
DOM event registration with auto-cleanup
Periodic tasks with overlap guards
Custom event bus for internal plugin communication

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | Memory leak | Using addEventListener directly | Always use registerDomEvent or registerEvent | | Stale data in handler | MetadataCache not resolved yet | Wait for resolved event before building index | | Handler fires before layout | Accessing workspace in onload | Wrap in onLayoutReady callback | | Handler runs after unload | Raw setInterval not cleared | Use registerInterval exclusively | | Performance hit from modify | Handler runs on every keystroke | Debounce the handler (500ms is a good default) | | Null leaf in active-leaf-change | All panes closed | Guard with if (leaf) check |

Examples

File Change Logger

// Log all file operations to a daily note
async onload() {
  const logEvent = async (action: string, path: string) => {
    const today = moment().format('YYYY-MM-DD');
    const logPath = `logs/${today}.md`;
    const line = `- ${moment().format('HH:mm:ss')} ${action}: ${path}`;
    await this.appendOrCreate(logPath, line);
  };

  this.registerEvent(this.app.vault.on('create', (f) => logEvent('created', f.path)));
  this.registerEvent(this.app.vault.on('delete', (f) => logEvent('deleted', f.path)));
  this.registerEvent(this.app.vault.on('rename', (f, old) => logEvent(`renamed from ${old}`, f.path)));
}

Tag Watcher — React to Frontmatter Tag Changes

private tagCache = new Map<string, string[]>();

async onload() {
  this.registerEvent(
    this.app.metadataCache.on('changed', (file, data, cache) => {
      const newTags = cache.frontmatter?.tags ?? [];
      const oldTags = this.tagCache.get(file.path) ?? [];

      const added = newTags.filter((t: string) => !oldTags.includes(t));
      const removed = oldTags.filter(t => !newTags.includes(t));

      if (added.length || removed.length) {
        this.onTagsChanged(file, added, removed);
      }

      this.tagCache.set(file.path, [...newTags]);
    })
  );
}

Resources

Next Steps

For throttling and debouncing these events under load, see obsidian-rate-limits. For production readiness, see obsidian-prod-checklist.

Agent Skills: Obsidian Webhooks & Events

Install this agent skill to your local

Skill Files