Self-Hosted Webhooks для Obsidian: Полное Руководство

Вы можете настроить приватный webhook сервер для Obsidian меньше чем за 10 минут. Это полное руководство проведет вас через hosted и self-hosted варианты с пошаговыми инструкциями для получения первого webhook в ваше хранилище.

Что такое Obsidian Webhooks?

Obsidian Webhooks Server — это self-hosted система доставки webhook, которая позволяет отправлять контент из любого внешнего сервиса напрямую в ваше хранилище Obsidian. Создаете ли вы заметки автоматически из Zapier, захватываете данные из кастомных скриптов или строите собственные интеграции — эта настройка дает вам надежный мост между вебом и вашими заметками.

Система использует Server-Sent Events (SSE) для доставки в реальном времени, PostgreSQL для персистентных очередей и AES-256-GCM шифрование для защиты ваших данных в процессе передачи. Подробнее об архитектуре — в руководстве Как работает Obsidian Webhooks.

Требования

Перед началом настройки убедитесь, что у вас есть:

• Obsidian Desktop (Windows, macOS или Linux)
• Docker и Docker Compose (для self-hosted варианта)
• Базовые знания терминала (запуск команд, редактирование файлов)
• Опционально: Домен с HTTPS для продакшн развертывания

Вариант A: Hosted версия (Быстрый старт)

Самый быстрый способ попробовать Obsidian webhooks — использовать бесплатную hosted версию на серверах EU (Германия, инфраструктура Supabase). Этот туториал начинается с hosted варианта перед погружением в self-hosting.

Шаг 1: Создайте аккаунт

1. Зайдите на obsidian-webhooks.khabaroff.studio
2. Введите ваш email адрес
3. Нажмите на magic link, отправленную на вашу почту
4. Вы попадете на дашборд с вашим webhook URL и vault key

Шаг 2: Установите Obsidian плагин

1. Откройте Obsidian Настройки → Community Plugins
2. Найдите и установите "obsidian-webhooks-2025"
3. Нажмите Install, затем Enable
4. Откройте настройки плагина
5. Введите URL сервера: https://obsidian-webhooks.khabaroff.studio
6. Вставьте ваш vault key (из дашборда)
7. Нажмите "Test Connection" для проверки

Шаг 3: Отправьте первый webhook

Откройте терминал и отправьте тестовый webhook:

curl -X POST https://obsidian-webhooks.khabaroff.studio/api/webhook \
  -H "Content-Type: application/json" \
  -H "X-Vault-Key: your-vault-key-here" \
  -d '{
    "path": "Inbox/Test Note.md",
    "mode": "create",
    "frontmatter": {
      "date": "2026-02-26",
      "source": "curl-test"
    },
    "content": "This is my first webhook-delivered note!"
  }'

В течение нескольких секунд вы увидите Test Note.md в папке Inbox вашего хранилища с этим содержимым:

---
date: 2026-02-26
source: curl-test
---
This is my first webhook-delivered note!

Hosted версия обрабатывает всю инфраструктуру, шифрование и доставку. Для большинства пользователей этого достаточно. Если вам нужен полный контроль над данными, переходите к Варианту B.

Вариант B: Self-Hosted Obsidian Webhook сервер

Эта Docker настройка дает вам полный контроль над данными и инфраструктурой.

Шаг 1: Клонируйте репозиторий

git clone https://github.com/khabaroff-studio/obsidian-webhooks-server.git
cd obsidian-webhooks-server

Шаг 2: Настройте переменные окружения

Скопируйте пример файла окружения:

cp .env.example .env

Отредактируйте .env в текстовом редакторе:

# Database (PostgreSQL)
DATABASE_URL=postgresql://webhooks:your-secure-password@postgres:5432/webhooks?sslmode=disable

# Encryption (generate with: openssl rand -hex 32)
ENCRYPTION_KEY=your-64-character-hex-key-here

# Server
PORT=8080
HOST=0.0.0.0

# Email (for magic link authentication)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-app-password
[email protected]

# Base URL (change for production)
BASE_URL=http://localhost:8080

Важные настройки:

• ENCRYPTION_KEY: Сгенерируйте командой openssl rand -hex 32. Это шифрует данные очереди.
• DATABASE_URL: Обновите пароль на безопасный.
• SMTP_*: Требуется для passwordless авторизации. Используйте Gmail app passwords или вашего SMTP провайдера.
• BASE_URL: Должен соответствовать вашему домену в продакшене (например, https://webhooks.yourdomain.com).

Шаг 3: Запустите с Docker Compose

docker-compose up -d

Это запустит два контейнера:

• postgres: База данных PostgreSQL 15
• server: Go приложение с webhook API и SSE доставкой

Проверьте, что они работают:

docker-compose ps

Вы должны увидеть оба контейнера со статусом "Up".

Шаг 4: Проверьте здоровье сервера

Проверьте, что API отвечает:

curl http://localhost:8080/health

Ожидаемый ответ:

{
  "status": "ok",
  "timestamp": "2026-02-26T10:30:00Z"
}

Шаг 5: Создайте первый Vault Key

1. Откройте http://localhost:8080 в браузере
2. Введите ваш email адрес
3. Нажмите на magic link в почте
4. На дашборде нажмите "Create Vault Key"
5. Дайте ему имя (например, "Personal Vault")
6. Скопируйте сгенерированный ключ (он понадобится для плагина)

Установите Obsidian плагин

Независимо от того, выбрали ли вы hosted или self-hosted, настройка плагина идентична.

Шаг 1: Установите из Community Plugins

1. Obsidian Настройки → Community Plugins
2. Выключите Restricted Mode если нужно
3. Browse → Найдите "obsidian-webhooks-2025"
4. Install и Enable

Шаг 2: Настройте подключение

1. Откройте настройки плагина
2. Server URL:
   • Hosted: https://obsidian-webhooks.khabaroff.studio
   • Self-hosted: http://localhost:8080 (или ваш домен)
3. Vault Key: Вставьте ключ из дашборда
4. Нажмите "Test Connection"

Вы должны увидеть: Connection successful. SSE stream is active.

Шаг 3: Настройте параметры доставки

В настройках плагина вы можете настроить:

• Default folder: Куда webhooks создают заметки (по умолчанию: Inbox/)
• Auto-create folders: Автоматически создавать родительские папки
• Reconnect on offline: Опрашивать пропущенные webhooks после сетевых обрывов
• Log level: Полезно для отладки доставки webhook

Отправьте ваш первый webhook

Теперь самое интересное. Давайте отправим данные из любого внешнего источника в ваше хранилище. Больше примеров — в 10 рецептах автоматизации.

Базовая структура webhook

curl -X POST http://localhost:8080/api/webhook \
  -H "Content-Type: application/json" \
  -H "X-Vault-Key: your-vault-key-here" \
  -d '{
    "path": "Inbox/My Note.md",
    "mode": "create",
    "frontmatter": {
      "date": "2026-02-26",
      "tags": ["automation", "test"]
    },
    "content": "# My First Webhook\n\nThis note was created via webhook."
  }'

Понимание режимов доставки

Поле mode контролирует, как обрабатывается контент:

1. Create Mode (По умолчанию)

Создает новую заметку. Если файл существует, добавляет числовой суффикс.

{
  "path": "Inbox/Daily Log.md",
  "mode": "create",
  "content": "Today's entry"
}

Если Daily Log.md существует, создает Daily Log 2.md.

2. Append Mode

Добавляет контент в конец существующей заметки.

{
  "path": "Inbox/Daily Log.md",
  "mode": "append",
  "content": "\n\n---\n\nNew entry at 10:30 AM"
}

Создает файл, если он не существует.

3. Overwrite Mode

Заменяет все содержимое файла.

{
  "path": "Inbox/Daily Log.md",
  "mode": "overwrite",
  "frontmatter": {
    "updated": "2026-02-26"
  },
  "content": "This replaces everything"
}

Обработка Frontmatter

Сервер автоматически конвертирует JSON в YAML frontmatter:

Webhook payload:

{
  "frontmatter": {
    "date": "2026-02-26",
    "tags": ["work", "project-x"],
    "priority": 1,
    "metadata": {
      "source": "api",
      "user_id": "abc123"
    }
  },
  "content": "Note content here"
}

Результат в хранилище:

---
date: 2026-02-26
tags:
  - work
  - project-x
priority: 1
metadata:
  source: api
  user_id: abc123
---
Note content here

Настройте поддержку нескольких хранилищ

Если у вас несколько хранилищ (например, Личное, Рабочее), создайте отдельные vault keys.

Шаг 1: Создайте дополнительные ключи

1. Дашборд → "Create Vault Key"
2. Имя: "Work Vault"
3. Скопируйте ключ

Шаг 2: Настройте второе хранилище

1. Откройте ваше второе хранилище в Obsidian
2. Установите тот же плагин
3. Введите тот же server URL
4. Вставьте второй vault key

Каждое хранилище получает только webhooks, отправленные на его конкретный ключ.

Шаг 3: Отправьте в конкретное хранилище

# Отправить в личное хранилище
curl -X POST http://localhost:8080/api/webhook \
  -H "X-Vault-Key: personal-vault-key" \
  -d '{"path": "Personal/Note.md", "content": "Personal note"}'

# Отправить в рабочее хранилище
curl -X POST http://localhost:8080/api/webhook \
  -H "X-Vault-Key: work-vault-key" \
  -d '{"path": "Work/Note.md", "content": "Work note"}'

Чеклист безопасности

Следуйте этим лучшим практикам для продакшн развертывания webhook сервера.

1. Используйте HTTPS в продакшене

Никогда не запускайте webhooks через HTTP в интернете. Настройте TLS:

Вариант A: Reverse Proxy (Рекомендуется)

Используйте Caddy или nginx с автоматическим Let's Encrypt:

# docker-compose.yml добавление
  caddy:
    image: caddy:2
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data

Caddyfile:

webhooks.yourdomain.com {
    reverse_proxy server:8080
}

Вариант B: Cloudflare Tunnel

HTTPS без конфигурации через Cloudflare:

cloudflared tunnel --url http://localhost:8080

2. Проверьте, что шифрование активно

Сервер использует AES-256-GCM шифрование для всех данных в очереди. Проверьте, что ваш ENCRYPTION_KEY установлен:

docker-compose exec server env | grep ENCRYPTION_KEY

Должна вывестись 64-символьная hex строка.

3. Ротируйте Vault Keys

Если ключ скомпрометирован:

1. Дашборд → Revoke key
2. Создайте новый ключ
3. Обновите настройки плагина в Obsidian
4. Обновите любые внешние сервисы, отправляющие webhooks

4. Защитите вашу базу данных

Измените стандартный пароль PostgreSQL в .env:

DATABASE_URL=postgresql://webhooks:use-strong-random-password-here@postgres:5432/webhooks

5. Мониторьте неудачные доставки

Проверьте логи сервера на проблемы:

docker-compose logs -f server

Ищите строки [ERROR] связанные с ошибками доставки.

Решение распространенных проблем

Webhook не приходит в хранилище

Проверка 1: SSE подключение

Настройки плагина → Connection Status должен показывать "Connected". Если показывает "Disconnected":

1. Проверьте, что server URL корректен
2. Проверьте, что firewall/сеть позволяет SSE соединения
3. Ищите ошибки в Obsidian Developer Console (Ctrl+Shift+I)

Проверка 2: Vault Key

Убедитесь, что заголовок X-Vault-Key в вашем webhook соответствует ключу в настройках плагина. Чувствителен к регистру.

Проверка 3: Логи сервера

docker-compose logs -f server | grep webhook

Ищите ID webhook и статус доставки.

Появляются дублирующиеся заметки

Система использует ACK (acknowledgment) подтверждение для предотвращения дубликатов. Если вы видите дубликаты:

1. Проверьте стабильность сети (обрывы могут вызывать повторы)
2. Проверьте, что версия плагина актуальна
3. Включите debug logging в настройках плагина

Система ACK работает так:

1. Сервер отправляет webhook через SSE
2. Плагин записывает файл в хранилище
3. Плагин отправляет ACK обратно серверу
4. Сервер удаляет webhook из очереди

Если шаг 3 не удается, сервер повторяет попытку (вызывая дубликаты). Плагин имеет встроенную дедупликацию на основе webhook ID.

Большие payload не проходят

Сервер имеет лимит 10 MB на заметку. Если вы упираетесь в это:

Решение 1: Разделите большой контент

Отправьте несколько webhooks с append mode:

# Часть 1
curl -X POST http://localhost:8080/api/webhook \
  -H "X-Vault-Key: your-key" \
  -d '{"path": "Large Note.md", "mode": "create", "content": "Part 1..."}'

# Часть 2
curl -X POST http://localhost:8080/api/webhook \
  -H "X-Vault-Key: your-key" \
  -d '{"path": "Large Note.md", "mode": "append", "content": "\nPart 2..."}'

Решение 2: Ссылка на внешние файлы

Храните большой контент отдельно и делайте ссылку:

{
  "path": "Index.md",
  "content": "See attached: [Report](https://yourdomain.com/report.pdf)"
}

SSE соединение постоянно обрывается

Если SSE stream часто отключается:

1. Проверьте таймауты reverse proxy: Caddy/nginx могут закрывать долгоживущие соединения
2. Мобильная синхронизация: SSE не работает на мобильных. Используйте polling fallback в настройках плагина.
3. Корпоративные сети: Некоторые блокируют SSE. Попробуйте другую сеть для теста.

Плагин автоматически переподключается и опрашивает пропущенные webhooks, так что это обычно прозрачно для пользователя.

Примеры webhook из реальной жизни

Пример 1: Интеграция с Zapier

Создайте заметку из Gmail:

1. Zapier trigger: New Email in Gmail
2. Zapier action: Webhooks by Zapier → POST
3. URL: http://localhost:8080/api/webhook
4. Headers: X-Vault-Key: your-key
5. Payload:

{
  "path": "Inbox/Email - {{subject}}.md",
  "mode": "create",
  "frontmatter": {
    "date": "{{received_date}}",
    "from": "{{from_email}}",
    "tags": ["email"]
  },
  "content": "# {{subject}}\n\n{{body_plain}}"
}

Пример 2: Ежедневный лог из Cron

Добавляйте в дневную заметку каждый час:

#!/bin/bash
# cron-log.sh

DATE=$(date +%Y-%m-%d)
TIME=$(date +%H:%M)

curl -X POST http://localhost:8080/api/webhook \
  -H "Content-Type: application/json" \
  -H "X-Vault-Key: your-key" \
  -d "{
    \"path\": \"Daily/${DATE}.md\",
    \"mode\": \"append\",
    \"content\": \"\\n- ${TIME}: System check completed\"
  }"

Добавьте в crontab:

0 * * * * /path/to/cron-log.sh

Пример 3: Readwise Highlights

Перенаправьте экспорты Readwise:

curl -X POST http://localhost:8080/api/webhook \
  -H "X-Vault-Key: your-key" \
  -d '{
    "path": "Books/{{book_title}}.md",
    "mode": "append",
    "content": "\n> {{highlight_text}}\n\n[[{{book_title}}]] - Page {{page_number}}"
  }'

Смотрите также: AI-агенты и Obsidian для продвинутых интеграций с Claude, GPT и кастомными агентами.

Следующие шаги

Теперь у вас есть рабочая настройка webhook. Вот что изучить дальше:

1. Рецепты автоматизации: Проверьте 10 рецептов автоматизации для 20+ готовых интеграций.
2. Zapier шаблоны: Импортируйте готовые Zaps для распространенных workflow.
3. API справка: Прочитайте полную API документацию для продвинутых функций.
4. Сообщество: Присоединяйтесь к GitHub Discussions чтобы делиться вашими автоматизациями.

Советы по производительности

• Batch webhooks: Отправляйте несколько заметок быстро подряд (SSE обрабатывает параллельную доставку)
• Используйте append mode: Более эффективно, чем создание множества маленьких файлов
• Мониторьте размер очереди: Дашборд показывает количество ожидающих webhooks

Стратегия бэкапов

Ваше хранилище уже синхронизировано (через Obsidian Sync или Git). Webhook сервер хранит минимальное состояние:

• База данных: Делайте бэкап PostgreSQL с pg_dump
• Vault keys: Экспортируйте из дашборда перед важными изменениями

# Бэкап базы данных
docker-compose exec postgres pg_dump -U webhooks webhooks > backup.sql

# Восстановление
docker-compose exec -T postgres psql -U webhooks webhooks < backup.sql

Заключение

Этот туториал охватил hosted и self-hosted настройки, от начальной установки до продакшн безопасности. Конфигурация Docker webhook дает вам надежный мост автоматизации, который доставляет webhooks меньше чем за секунду, с гарантиями exactly-once и офлайн синхронизацией.

Захватываете ли вы emails, синхронизируете highlights или строите кастомные интеграции — эта настройка автоматизации масштабируется от одного хранилища до мультихранилищных команд.

Self-hosted вариант (MIT лицензия) означает, что вы полностью контролируете свои данные, в то время как hosted версия (бесплатно на EU серверах) позволяет начать за 60 секунд.

Начните автоматизировать ваше Obsidian хранилище сегодня на obsidian-webhooks.khabaroff.studio или клонируйте GitHub репозиторий для self-hosting.

---

Дополнительные ресурсы

• GitHub Repository — Исходный код и API документация
• Страница плагина — Установите сопутствующий плагин
• Landing Page — Регистрация hosted версии
• Коллекция рецептов — Готовые шаблоны автоматизации
• REST API vs Webhooks — Сравнение подходов к интеграции