Вебхуки: как сайт и сервисы общаются в реальном времени

Представьте, что вместо того, чтобы каждые 5 секунд звонить в пиццерию «Мой заказ готов?», курьер сам звонит вам, когда пицца на месте. Вот это и есть вебхуки — способ получать уведомления о событиях в реальном времени, без бесконечных запросов к API.

Вебхуки vs Поллинг

Критерий	Поллинг	Вебхуки
Принцип	Вы опрашиваете API каждые N секунд	Сервис сам отправляет запрос на ваш URL
Нагрузка на API	Высокая (99% запросов впустую)	Минимальная (только реальные события)
Задержка	От N секунд до минут	Секунды
Сложность	Проще начать	Нужен публичный URL
Надёжность	Вы контролируете	Зависит от ретраев отправителя

Как работает вебхук

Вы регистрируете URL-эндпоинт (webhook URL) в настройках сервиса
Когда происходит событие (оплата, новое сообщение, коммит), сервис отправляет POST-запрос на ваш URL
Ваш сервер обрабатывает данные и возвращает 200 OK
Если ваш сервер не ответил или вернул ошибку — сервис повторит попытку

Приём вебхуков на PHP

Простой обработчик вебхука от платёжной системы:

<?php
// webhook.php — обработчик вебхука ЮKassa

$body = file_get_contents('php://input');
$data = json_decode($body, true);

if (!$data || !isset($data['event'])) {
    http_response_code(400);
    exit('Invalid payload');
}

// Логируем входящий запрос
file_put_contents(
    __DIR__ . '/webhook.log',
    date('Y-m-d H:i:s') . ' ' . $body . PHP_EOL,
    FILE_APPEND
);

switch ($data['event']) {
    case 'payment.succeeded':
        $payment = $data['object'];
        $orderId = $payment['metadata']['order_id'];
        $amount = $payment['amount']['value'];

        // Обновляем статус заказа
        updateOrderStatus($orderId, 'paid');

        // Отправляем email покупателю
        sendConfirmationEmail($orderId);
        break;

    case 'payment.canceled':
        $payment = $data['object'];
        $orderId = $payment['metadata']['order_id'];
        updateOrderStatus($orderId, 'canceled');
        break;

    case 'refund.succeeded':
        handleRefund($data['object']);
        break;

    default:
        // Неизвестное событие — логируем, но возвращаем 200
        error_log("Unknown webhook event: " . $data['event']);
}

http_response_code(200);
echo 'OK';

Приём вебхуков на Node.js (Express)

const express = require('express');
const crypto = require('crypto');

const app = express();

// Важно: для проверки подписи нужен raw body
app.use('/webhook', express.raw({ type: 'application/json' }));

app.post('/webhook/stripe', (req, res) => {
  const signature = req.headers['stripe-signature'];
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;

  let event;

  try {
    event = verifyStripeSignature(req.body, signature, webhookSecret);
  } catch (err) {
    console.error('Webhook signature verification failed:', err.message);
    return res.status(400).send('Invalid signature');
  }

  // Обрабатываем событие
  switch (event.type) {
    case 'checkout.session.completed':
      const session = event.data.object;
      handleSuccessfulPayment(session);
      break;

    case 'invoice.payment_failed':
      const invoice = event.data.object;
      handleFailedPayment(invoice);
      break;

    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  // Всегда возвращаем 200 быстро!
  res.json({ received: true });
});

app.listen(3000);

Проверка подписи (HMAC)

Без проверки подписи любой может отправить фейковый запрос на ваш webhook URL. Большинство сервисов подписывают запросы с помощью HMAC-SHA256.

Как это работает

Сервис берёт тело запроса и вычисляет HMAC с секретным ключом
Результат передаётся в заголовке (например, X-Signature)
Ваш сервер вычисляет HMAC тем же ключом и сравнивает

PHP: проверка HMAC

function verifyWebhookSignature(
    string $body,
    string $receivedSignature,
    string $secret
): bool {
    $computedSignature = hash_hmac('sha256', $body, $secret);

    // Используем hash_equals для защиты от timing-атак
    return hash_equals($computedSignature, $receivedSignature);
}

// Использование
$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$secret = getenv('WEBHOOK_SECRET');

if (!verifyWebhookSignature($body, $signature, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

Node.js: проверка HMAC

function verifySignature(body, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  // timingSafeEqual для защиты от timing-атак
  return crypto.timingSafeEqual(
    Buffer.from(computed, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

Идемпотентность: защита от дублей

Вебхуки могут приходить повторно — если ваш сервер ответил медленно, сервис отправит запрос ещё раз. Ваш обработчик должен быть идемпотентным: повторная обработка того же события не должна ломать данные.

// Храним обработанные event ID
const processedEvents = new Set(); // В продакшене — Redis или БД

app.post('/webhook', (req, res) => {
  const eventId = req.body.id;

  if (processedEvents.has(eventId)) {
    console.log(`Event ${eventId} already processed, skipping`);
    return res.json({ received: true });
  }

  // Обрабатываем событие
  processEvent(req.body);

  processedEvents.add(eventId);
  res.json({ received: true });
});

Retry-логика со стороны отправителя

Большинство сервисов повторяют запросы по экспоненциальной схеме:

Попытка	Задержка	Пример (Stripe)
1	Сразу	0 сек
2	~1 мин	60 сек
3	~5 мин	300 сек
4	~30 мин	1800 сек
5	~2 часа	7200 сек

Если после всех попыток ваш сервер не ответил 200, сервис помечает вебхук как failed и может отключить endpoint.

Правило: отвечайте 200 OK как можно быстрее, а тяжёлую обработку выносите в фоновую очередь.

Локальная разработка: ngrok

При разработке ваш localhost недоступен из интернета. Решение — ngrok:

# Установка
npm install -g ngrok

# Запуск туннеля
ngrok http 3000

# Результат:
# Forwarding https://a1b2c3d4.ngrok-free.app -> http://localhost:3000

# Теперь используйте https://a1b2c3d4.ngrok-free.app/webhook
# как webhook URL в настройках сервиса

Альтернативы ngrok: Cloudflare Tunnel (бесплатный), localtunnel, bore.

Сервис	Заголовок подписи	Алгоритм	Документация
Stripe	Stripe-Signature	HMAC-SHA256 + timestamp	stripe.com/docs/webhooks
ЮKassa	—	IP whitelist	yookassa.ru/developers
GitHub	X‑Hub-Signature-256	HMAC-SHA256	docs.github.com/webhooks
Telegram	—	Secret token в заголовке	core.telegram.org/bots/api
T‑Bank	—	SHA-256 от конкатенации полей	www.tbank.ru/kassa/dev

Архитектура для продакшена

Для надёжной обработки вебхуков используйте очередь:

// 1. Endpoint только принимает и кладёт в очередь
app.post('/webhook', async (req, res) => {
  if (!verifySignature(req.body, req.headers['x-signature'])) {
    return res.status(401).send('Invalid signature');
  }

  // Кладём в очередь (Redis, RabbitMQ, SQS)
  await queue.add('webhook-processing', {
    event: req.body,
    receivedAt: new Date().toISOString(),
  });

  // Отвечаем мгновенно
  res.json({ received: true });
});

// 2. Worker обрабатывает события из очереди
queue.process('webhook-processing', async (job) => {
  const { event } = job.data;

  // Проверка на дубль
  const exists = await redis.get(`webhook:${event.id}`);
  if (exists) return;

  // Обработка
  await processEvent(event);

  // Помечаем как обработанный (TTL 7 дней)
  await redis.set(`webhook:${event.id}`, '1', 'EX', 604800);
});