HTTP hooks — вебхук как реакция

Почему это важно именно вам

Вы работаете с десятками инструментов одновременно: Telegram для оперативной связи, Google Sheets для данных, make.com или n8n для автоматизации бизнес-процессов. Claude Code тоже часть этой экосистемы — но до сих пор он работал в изоляции. Он создавал файлы, писал отчёты, анализировал данные — и всё это оставалось внутри терминала. Вы узнавали о результате только когда смотрели на экран.

HTTP hooks меняют это. Когда Claude завершает задачу, создаёт файл или вызывает инструмент — система сама посылает сигнал во внешний мир. В Telegram прилетает сообщение «отчёт готов, вот ссылка». В Google Sheets появляется новая строка с временной меткой. В make.com запускается сценарий обработки. Всё это происходит автоматически, без вашего участия, в тот момент когда нужно, а не когда вы случайно заглянули в терминал.

Для директора, который ведёт несколько проектов параллельно, это принципиальный сдвиг. Вы не должны постоянно следить за процессом — процесс сам вас найдёт в нужный момент. Это та самая разница между «я управляю задачами» и «задачи уведомляют меня».

Что это такое

Вебхук — слово, которое в IT произносят часто и объясняют редко. Давайте через простую аналогию.

Представьте курьерскую службу. Есть два варианта отслеживания посылки. Первый: вы каждый час заходите на сайт и смотрите статус. Второй: вы оставляете телефон, и вам звонят когда посылка прибыла. Вебхук — это второй вариант. Вместо того чтобы вы постоянно опрашивали систему («есть что-то новое?»), система сама вас уведомляет когда что-то произошло.

В техническом смысле: вебхук — это HTTP POST-запрос, который одна система посылает другой при наступлении события. Вы говорите Claude Code: «при таком-то событии — отправь POST-запрос на такой-то URL». Claude Code при наступлении события формирует JSON с данными и отправляет его на ваш URL. Что там находится на том конце URL — Telegram-бот, Google Apps Script, make.com сценарий — Claude не знает и не должен знать.

HTTP hook — это не новая технология

Вебхуки используются повсюду: Stripe посылает вебхук когда проходит оплата, GitHub — когда кто-то пушит код, Marquiz — когда заполняется квиз. Вы, скорее всего, уже получали вебхуки на стороне приёма. HTTP hooks в Claude Code позволяют его самому быть источником таких событий.

Тип http — один из пяти типов реакций: command (шелл-команда), http (POST на URL), mcp_tool (вызов инструмента подключённого MCP-сервера), prompt (одноходовая оценка моделью, возвращает вердикт) и экспериментальный agent (проверяющий субагент с инструментами). Тип http специально создан для интеграций: когда нужно не что-то выполнить локально, а уведомить внешний сервис.

Как работает на практике

Начнём с минимальной рабочей конфигурации. HTTP hook описывается в файле ~/.claude/settings.json или в .claude/settings.json вашего проекта. Вот структура:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://your-endpoint.com/webhook",
            "headers": {
              "Content-Type": "application/json",
              "Authorization": "Bearer your-token"
            },
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Разберём каждый параметр:

url — адрес куда летит запрос. Это может быть ваш Telegram-бот через API, Google Apps Script, make.com webhook URL, n8n endpoint или любой другой сервис, который умеет принимать POST-запросы.

headers — HTTP-заголовки. Обычно там Content-Type: application/json (всегда нужен) и авторизация. Большинство сервисов используют Authorization: Bearer <токен> или свой собственный заголовок — например, make.com просто использует URL с секретом без отдельного заголовка.

timeout — сколько секунд ждать ответа от сервиса. По умолчанию 600 секунд, что для вебхука заведомо много: ставьте 10–15 явно. Если сервис не ответил — hook завершается с ошибкой, но Claude продолжает работу. Уменьшайте до 3-5 для Telegram (быстрый), оставляйте 10-15 для make.com (может думать дольше).

Что приходит на другой конец

Когда Claude Code отправляет вебхук, тело запроса — это JSON с данными события. Для события PostToolUse с инструментом Write это выглядит примерно так:

{
  "session_id": "abc123",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/Users/pavel/reports/analysis-2026-06-03.md",
    "content": "..."
  },
  "tool_response": {
    "success": true
  }
}

Из этого JSON вы можете вытащить tool_input.file_path чтобы знать какой файл создан, проверить tool_response.success чтобы убедиться что всё прошло успешно, и сформировать понятное уведомление.

Пример 1: Уведомление в Telegram при создании отчёта

Самый частый запрос. Claude создаёт файл отчёта — вам прилетает сообщение в Telegram.

Шаг 1. Создайте Telegram-бота через @BotFather, получите токен вида 1234567890:AAF....

Шаг 2. Узнайте ваш Telegram chat_id. Напишите боту любое сообщение, затем откройте в браузере:

https://api.telegram.org/bot<ваш_токен>/getUpdates

В ответе найдите "chat": {"id": 252679756} — это ваш chat_id.

Шаг 3. Создайте скрипт-прослойку. Дело в том, что HTTP hook посылает один запрос, но Telegram API требует конкретного формата. Проще всего использовать Google Apps Script как мост — он бесплатный и не требует сервера.

Создайте новый Apps Script (script.google.com), вставьте:

function doPost(e) {
  const data = JSON.parse(e.postData.contents);
  const filePath = data.tool_input?.file_path || "неизвестный файл";
  const fileName = filePath.split("/").pop();

  const token = "ВАШ_TELEGRAM_TOKEN";
  const chatId = "ВАШ_CHAT_ID";
  const text = `Claude создал файл: ${fileName}`;

  UrlFetchApp.fetch(
    `https://api.telegram.org/bot${token}/sendMessage`,
    {
      method: "post",
      contentType: "application/json",
      payload: JSON.stringify({ chat_id: chatId, text: text })
    }
  );

  return ContentService.createTextOutput("ok");
}

Опубликуйте как веб-приложение (Deploy → New deployment → Web app, доступ для всех). Получите URL вида https://script.google.com/macros/s/ABC.../exec.

Шаг 4. Добавьте hook в .claude/settings.json вашего рабочего проекта:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://script.google.com/macros/s/ABC.../exec",
            "headers": {
              "Content-Type": "application/json"
            },
            "timeout": 15
          }
        ]
      }
    ]
  }
}

Теперь каждый раз когда Claude создаёт файл — вам в Telegram прилетает уведомление с именем файла.

Пример 2: Запись в Google Sheets при завершении задачи

Событие Stop срабатывает когда Claude заканчивает работу. Полезно для ведения лога задач.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://script.google.com/macros/s/XYZ.../exec",
            "headers": {
              "Content-Type": "application/json"
            },
            "timeout": 10
          }
        ]
      }
    ]
  }
}

В Apps Script для записи в Sheets:

function doPost(e) {
  const data = JSON.parse(e.postData.contents);
  const sheet = SpreadsheetApp.openById("ВАШ_ID_ТАБЛИЦЫ").getActiveSheet();

  sheet.appendRow([
    new Date(),
    data.session_id || "",
    "завершено"
  ]);

  return ContentService.createTextOutput("ok");
}

Событие Stop — без matcher

Для события Stop поле matcher не нужно — это конечное событие сессии, оно не привязано к конкретному инструменту. То же касается PreToolUse и PostToolUse без matcher — тогда hook срабатывает на любой инструмент.

Пример 3: Триггер make.com workflow

make.com (бывший Integromat) умеет принимать вебхуки нативно. В сценарии добавьте модуль «Webhooks → Custom webhook», скопируйте URL.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "https://hook.eu1.make.com/abc123def456",
            "headers": {
              "Content-Type": "application/json"
            },
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Теперь каждый раз когда Claude выполняет команду в терминале — make.com сценарий запускается и может делать что угодно: создавать задачи в Jira, обновлять записи в CRM, отправлять email.

Частые ошибки

Ошибка 1: Настройка allowedHttpHookUrls

Тело запроса и заголовок Content-Type: application/json Claude Code проставляет сам — указывать их не нужно. А вот что действительно ломает HTTP-хуки — настройка allowedHttpHookUrls: если она задана на любом уровне настроек, хук пойдёт только на адреса из этого списка.

Ошибка 2: Слишком маленький timeout

Поставили "timeout": 2 и думаете что экономите время. На практике: Apps Script иногда «холодный» и первый запрос занимает 4-6 секунд. make.com при сложном сценарии — 8-12 секунд. При timeout: 2 hook будет постоянно падать с ошибкой, но Claude об этом почти не сигнализирует — просто продолжит работу. Ставьте минимум 10 секунд для внешних сервисов.

Ошибка 3: Matcher написан с ошибкой

"matcher": "write" вместо "matcher": "Write" — с маленькой буквы. Имена инструментов в Claude Code регистрозависимы: Write, Read, Bash, Edit. Если matcher не совпадает — hook просто не срабатывает, никакой ошибки вы не увидите. Проверяйте точное написание инструментов.

Ошибки в HTTP hooks молчаливы

Если вебхук не дошёл — Claude не остановится и не предупредит. Он продолжит работу как будто ничего не произошло. Это правильное поведение: задача важнее уведомления. Но это значит что вы должны сами проверять работу hooks при первоначальной настройке — отправьте тестовый запрос вручную через curl или Postman прежде чем полагаться на hook в работе.

Ошибка 4: Токены прямо в settings.json который лежит в проекте

Если ваш .claude/settings.json лежит в рабочей папке, которая синхронизируется с Яндекс.Диском или хранится в git-репозитории — любые токены в headers окажутся в облаке. Токен можно подставить прямо в заголовок из переменной окружения — для этого её имя перечисляют в allowedEnvVars:

{ "type": "http", "url": "...", "timeout": 15,
  "headers": { "Authorization": "Bearer $MY_TOKEN" },
  "allowedEnvVars": ["MY_TOKEN"] }

Без allowedEnvVars подстановка не сработает и в заголовок уйдёт пустая строка. Для личных глобальных настроек ~/.claude/settings.json риск меньше — этот файл не синхронизируется.

Когда нужно / когда нет

HTTP hook нужен, когда:

Вы хотите получать уведомления о работе Claude без постоянного слежения за терминалом. Особенно актуально для долгих задач — анализ большого файла, обработка данных.
Нужно интегрировать Claude в существующие рабочие процессы: уведомление в командный чат, запись в общую таблицу учёта задач, триггер для следующего шага в автоматизации.
Claude работает в фоновом режиме (--bg, из дня 9) и вы хотите знать когда он закончил.
Разные события требуют разных реакций — один hook на создание файла, другой на завершение задачи, третий на ошибку.

HTTP hook не нужен, когда:

Вам достаточно просто посмотреть на экран когда задача закончится — не усложняйте.
Задача занимает 30 секунд — уведомление придёт раньше чем вы успеете отвлечься.
Нужно что-то сделать локально (переименовать файл, запустить скрипт) — для этого тип command из дня 45 проще и надёжнее.
Вы не контролируете endpoint — если сервис недоступен, вебхук потеряется без повтора. Для критичных данных нужна другая архитектура.

HTTP hook и command hook часто работают в паре

Типичный сценарий: command hook проверяет условие и решает, нужно ли уведомлять, затем HTTP hook отправляет уведомление. Или наоборот: HTTP hook запускает внешний процесс, а command hook фиксирует результат локально. Их можно комбинировать в одном событии — несколько hooks выполняются последовательно.

Связь с другими уроками

День 41 — «Что такое hooks и как они работают»: там разобрана общая модель — события, matchers, порядок выполнения. HTTP hook — один из типов реакции внутри этой модели. Если события и matchers кажутся непонятными, стоит вернуться к дню 41.

День 45 — «command hooks»: тип command и тип http — два разных инструмента для разных задач. Command выполняет локальные скрипты, HTTP уведомляет внешние сервисы. Они не конкурируют — вы можете использовать оба для одного события. День 45 объясняет, как написать скрипт, который Claude запускает через command hook.

Дни 48–49 — «аудит и нотификации»: там собрана практика построения системы мониторинга на основе hooks — когда уведомлять, о чём, как организовать очередь уведомлений чтобы не утонуть в сообщениях. HTTP hooks из сегодняшнего урока — строительный материал для той системы.

Задание на сегодня

Настройте один рабочий HTTP hook — уведомление в Telegram когда Claude создаёт файл.

Конкретные шаги:
1. Создайте бота через @BotFather, запишите токен.
2. Узнайте ваш chat_id через getUpdates.
3. Создайте Google Apps Script с функцией doPost из примера выше, опубликуйте, скопируйте URL.
4. Добавьте hook в .claude/settings.json вашего рабочего проекта.
5. Попросите Claude: создай файл test-hook.md с текстом "проверка".

Критерий выполнено: в Telegram пришло сообщение «Claude создал файл: test-hook.md» — hook работает.

Если что-то пошло не так — проверьте Apps Script в разделе Executions, там видны все входящие запросы и ошибки.

Резюме

HTTP hook — это POST-запрос который Claude Code посылает на внешний URL при наступлении события. Вы описываете в settings.json три вещи: какое событие, какой URL, какие заголовки.
Тело запроса всегда JSON с данными события: имя инструмента, его входные параметры, результат выполнения. Принимающий сервис сам решает что с этим делать.
Google Apps Script — удобный бесплатный мост между Claude Code и Telegram или Google Sheets: принимает вебхук, форматирует данные, отправляет дальше.
Ошибки в HTTP hooks молчаливы — Claude продолжает работу даже если вебхук не дошёл. Проверяйте работу hooks при настройке через тестовые запросы.
Не кладите токены в settings.json который синхронизируется в облако — используйте URL с секретом или переменные окружения.