Как проверить вебхук на localhost: тестовый POST и публичный HTTPS

Запустите локальный обработчик и отправьте ему тестовый POST через curl. Когда он ответит HTTP 200, повторите тот же запрос по публичному HTTPS-адресу. Так можно проверить приложение и туннель по отдельности, прежде чем подключать отправителя.

1. Запустите тестовый обработчик

Сохраните пример в webhook.mjs и запустите node webhook.mjs. Нужен Node.js, дополнительных пакетов нет. Обработчик принимает только тестовый JSON размером до 8 КиБ и пишет в консоль фиксированное сообщение. Для демонстрации используйте вымышленные события.

import { createServer } from 'node:http';

createServer(async (req, res) => {
  if (req.url !== '/webhook') {
    res.writeHead(404).end();
    return;
  }
  if (req.method !== 'POST') {
    res.writeHead(405, { Allow: 'POST' }).end();
    return;
  }

  let size = 0;
  const chunks = [];
  try {
    for await (const chunk of req.iterator({ destroyOnReturn: false })) {
      size += chunk.length;
      if (size > 8192) {
        res.writeHead(413, { Connection: 'close' }).end();
        return;
      }
      chunks.push(chunk);
    }
  } catch {
    res.destroy();
    return;
  }

  try {
    JSON.parse(Buffer.concat(chunks).toString('utf8'));
  } catch {
    res.writeHead(400).end();
    return;
  }

  console.log('Тестовый POST получен');
  res.writeHead(200, { 'Content-Type': 'application/json' }).end('{"ok":true}');
}).listen(3000, '127.0.0.1');

2. Отправьте POST на localhost

curl -i http://127.0.0.1:3000/webhook \
  -H 'Content-Type: application/json' \
  --data '{"event":"test.ping"}'

Ожидайте HTTP 200, тело {"ok":true} и строку «Тестовый POST получен» в терминале Node.js. Если локальный запрос не работает, проверьте, запущен ли процесс и свободен ли порт 3000.

3. Повторите запрос через HTTPS

Оставьте Node.js запущенным и откройте второй терминал.

ssh -p 2222 -o ExitOnForwardFailure=yes -R 80:127.0.0.1:3000 tunnelhunt.ru

Подставьте выданный HTTPS-адрес вместо примера. Сохраните путь /webhook.

curl -i https://YOUR-SUBDOMAIN.tunnelhunt.ru/webhook \
  -H 'Content-Type: application/json' \
  --data '{"event":"test.ping"}'

Дождитесь HTTP 200 и второй строки в терминале Node.js. Для сессии Free добавьте публичный SSH-ключ в кабинете. Помощь с первым подключением есть в гайде по открытию localhost.

Результат	Что проверить
Локально не удаётся подключиться	Запущен ли Node.js и совпадает ли порт с командой.
Локально 200, по HTTPS 502	Открыта ли SSH-сессия и может ли её клиент подключиться к 127.0.0.1:3000.
404 или 405	Укажите путь /webhook и отправьте POST. Открытие ссылки в браузере отправляет GET.
400 или 413	Проверьте JSON и размер тела.
Тестовый POST работает, событие от сервиса не приходит	Проверьте полный URL и журнал доставок отправителя. Если интеграция требует подпись или ответ на проверочный запрос, реализуйте их по инструкции провайдера.

4. Подключите тестового отправителя

Для настоящих событий настройте проверку подписи или секрета по правилам отправителя и обработку повторных доставок. Этот учебный обработчик подходит для проверки маршрута искусственным JSON. Используйте отдельный тестовый проект или тестовый режим.

• Telegram Bot API — секрет вебхука и диагностика через getWebhookInfo.
• GitHub — тестовый ping и проверка HMAC.
• n8n — тестовый и рабочий URL узла Webhook.
• Платёжные системы — инструкции для ЮKassa, Т-Банка, CloudPayments и Robokassa.

Если событие уже дошло и вы хотите повторить его после исправления кода, используйте руководство по Replay. После теста закройте SSH-сессию и остановите обработчик.