Skip to Content
Документация для разработчиковРешение проблемВебхук не срабатывает

Если вебхук молчит, вкладка дашборда Вебхук → Логи говорит почти всё в одном экране. Откройте её первым.

Шаг 1: Проверьте логи доставок

Настройки → Вебхуки → <webhook> → Логи показывает каждую попытку доставки за 30 дней. Три вещи:

  • Есть ли строка для ожидаемого события? Если нет — триггер не отработал на платформе, см. Срабатывает только на тестах ниже.
  • Какой статус-код вернул эндпоинт? Кликните по строке, чтобы посмотреть headers и body.
  • Сколько занял запрос? > 10 секунд = таймаут.

Срабатывает только на тестах

Кнопка Отправить тестовое событие работает, но реальные события не приходят.

Вероятная причина

Событие, которое вы ожидали, на самом деле не было создано действием, которое вы выполнили.

Как подтвердить

В дашборде откройте вкладку Events и отфильтруйте по типу. Если ни одного события нет — RevRoute его не производил.

Типичные причины:

  • link.clicked — вебхук workspace-уровня вместо link-уровня. link.clicked срабатывает только для вебхуков, прикреплённых к конкретной ссылке, не всему workspace.
  • lead.created — дедупликация подавила событие, потому что такая связка customerExternalId + eventName уже существует.
  • sale.created — продажа дублирующая (тот же invoiceId уже записан).
  • partner.application_submitted — webhook программного уровня на другой программе, не той, куда подали заявку.

Несовпадение подписи

Эндпоинт получает запрос, но проверка подписи отклоняет.

Причины (по убыванию вероятности)

  1. Тело распарсилось до хэширования. req.body — распарсенный объект, но подписывается сырое содержимое. Пересериализация переставляет ключи. Получайте сырое тело — см. Проверка подписи.
  2. Неверный секрет в env. Перепутаны dev и prod, или старое значение после ротации. Напечатайте префикс (первые 8 символов), чтобы сравнить без утечки.
  3. Reverse-прокси сжимает или меняет тело. CDN или middleware фреймворка, которое gzip’ит, pretty-print’ит, обрезает пробелы — сломает подпись. Проверяйте до того, как тело попадает в middleware.
  4. Опечатка в имени header’а. Header — Revroute-Signature (case-insensitive в HTTP, но некоторые фреймворки нормализуют странно). Используйте case-insensitive getter фреймворка.
  5. Сравнение через === и одна из сторон в binary. Нормализуйте обе в lowercase-hex перед сравнением.

Быстрая проверка

# Берёте реальное захваченное тело и секрет, пересчитываете, сравниваете
echo -n '<тело здесь>' | openssl dgst -sha256 -hmac '<секрет>' -hex

Если результат не совпадает с Revroute-Signature той доставки — байты тела не те, что вы думаете.

Авто-отключение

Дашборд показывает webhook как отключен.

Причина

20 подряд доставок упали. Чтобы прекратить бесконечные ретраи в мёртвый эндпоинт, RevRoute ставит webhook на паузу.

Решение

•

Почините коренную проблему

Посмотрите последний failing-лог — всегда 5xx, timeout, или connection refused? Решите это.

•

Отправьте тестовое событие

Из дашборда нажмите Отправить тестовое событие. Подтвердите, что вернулся 2xx.

•

Включите webhook обратно

Переключите webhook в Enabled. Будущие события будут доставлены. Внимание: события, фаерившие во время отключения, не реплеятся.

Конкретные прошлые события можно вручную реплеить из вкладки Logs, если нужен backfill.

Таймауты

Логи показывают Timeout (10s) или эндпоинт частично обработал и был убит.

Причина

RevRoute ждёт 2xx до 10 секунд. Если обработчик делает тяжёлую работу синхронно — под нагрузкой будете таймаутить.

Решение

Обработчик должен:

  1. Проверить подпись
  2. Сохранить id события и сырой payload в БД
  3. Сразу ответить 200
  4. Обработать событие в фоне (очередь, cron, durable workflow)
export async function POST(req: NextRequest) {
  const raw = await req.text();
  verifySignature(raw, req.headers.get("Revroute-Signature"));
 
  await db.webhookEvents.insert({
    id: JSON.parse(raw).id,
    payload: raw,
    receivedAt: new Date(),
  });
 
  // Не await — кладём в очередь и возвращаем
  void enqueueProcessing(JSON.parse(raw).id);
  return new NextResponse("ok");
}

200ms-обработчик никогда не таймаутит при нормальных условиях.

Эндпоинт недоступен

Логи показывают Connection refused, DNS error, или Connection reset.

Причины

  • DNS вашего домена неправильный — проверьте dig +short yourdomain.com.
  • Файервол блокирует исходящие IP RevRoute.
  • Эндпоинт за VPN или в приватной сети — webhook-эндпоинты должны быть публично доступны.
  • Health-check балансировщика падает, и маршрутизация сломана.

Решение

# С любой машины с интернетом проверьте, что эндпоинт отвечает на пустой POST
curl -X POST https://yourapp.com/api/webhooks/revroute -d '{}'

Если падает с вашего ноутбука — RevRoute тоже упадёт. Сначала сетевой уровень.

TLS / SSL-ошибки

Логи показывают SSL handshake failed или Certificate verification failed.

Причины

  • Self-signed сертификат. RevRoute требует публично доверенный CA.
  • Истёкший сертификат.
  • Несовпадение hostname — сертификат не покрывает конкретный hostname.
  • Отсутствуют intermediate-сертификаты (цепочка неполна).

Решение

Прогоните через SSL Labs  — он покажет всё вышеуказанное и точно скажет, что чинить. Grade B или выше требуется для webhook-доставок.

Out-of-order доставка

Вы видите sale.created, пришедший раньше lead.created для того же клиента.

Причина

Webhook-доставки не упорядочены. Два события, сработавших близко по времени, могут прийти в любом порядке.

Решение

Не полагайтесь на порядок событий. Сделайте обработчики идемпотентными и толерантными к любой последовательности:

  • Получив sale.created для неизвестного клиента, посмотрите lead позже через API.
  • Храните события по их id, чтобы повторные доставки были no-op.

См. также: Обзор вебхуков, Проверка подписи.

Last updated on
Проблемы трекингаОшибки API