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

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

• Obsidian Events API
• Workspace Events
• Vault Events
• MetadataCache API

Next Steps

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