Вебхуки

Уведомления о статусах счетов — создаются только через веб-кабинет

Главное

Вебхуки настраиваются только через веб-кабинет. Публичного API для создания/изменения/удаления вебхуков нет — это сделано осознанно для предотвращения атак на ваш endpoint через утёкший API-ключ.

В этом руководстве — как создать вебхук в UI, какие события доступны, как проверять HMAC-подпись и обрабатывать retry-логику.

Создание вебхука

1. Откройте раздел в кабинете

   Панель управления → Вебхуки

2. Нажмите «Создать вебхук»

   Заполните форму:

   • URL — куда отправлять POST. Должен быть HTTPS в production.
   • События — отметьте нужные галочки (см. список ниже).
   • Описание (опционально) — для своих заметок.
3. Скопируйте секрет

   После создания система покажет Webhook Secret — уникальный ключ для этого вебхука. Сохраните его — он нужен для проверки HMAC-подписи входящих запросов.

   Секрет можно посмотреть позже в карточке вебхука — он не одноразовый, в отличие от API-секрета.
4. Проверьте доставку

   В карточке вебхука есть кнопка «Тест» — отправит проверочный POST на ваш URL с фиктивным payload’ом. Если у вас 2xx — вебхук работает.

Доступные события

Событие	Когда срабатывает
invoice.paid	Клиент оплатил счёт
invoice.expired	Истёк час, счёт стал EXPIRED
invoice.cancelled	Партнёр отменил счёт
invoice.refunded	Выполнен возврат (полный или частичный)
kyc.passed	Клиент успешно прошёл KYC
kyc.rejected	KYC отклонён (failed-verification)
kyc.manual_review	KYC отправлен на ручную проверку

Формат payload

POST на ваш URL с JSON-телом и HMAC-заголовком:

POST https://your-server.com/lovepay-webhook HTTP/1.1
Content-Type: application/json
X-LNP-Event: invoice.paid
X-LNP-Signature: 7d2a8b3c...
X-LNP-Timestamp: 1716207600000
X-LNP-Delivery: 4f8e9a1d-xxxx-...

{
  "event": "invoice.paid",
  "timestamp": 1716207600000,
  "invoice": {
    "id": "uuid",
    "invoiceNumber": "INV-260520-0042",
    "amount": 150050,
    "status": "PAID",
    "paidAt": "2026-05-20T14:00:00.000Z",
    "metadata": { "orderId": "12345" },
    "customerEmail": "[e-mail]",
    "customerPhone": "[phone]"
  }
}

Поле metadata всегда возвращается из того, что вы передали при создании счёта.

Проверка HMAC-подписи (обязательно!)

Перед обработкой всегда проверяйте X-LNP-Signature — иначе любой может вам слать фейковые “оплачено”. Подпись = HMAC-SHA256(webhook_secret, timestamp + raw_body).

Node.js

const crypto = require('crypto')

app.post('/lovepay-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-lnp-signature']
  const timestamp = req.headers['x-lnp-timestamp']
  const body = req.body.toString('utf8')

  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(timestamp + body)
    .digest('hex')

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).end('Invalid signature')
  }

  // Защита от replay: не принимать события старше 5 минут
  if (Math.abs(Date.now() - parseInt(timestamp)) > 5 * 60 * 1000) {
    return res.status(401).end('Timestamp expired')
  }

  const event = JSON.parse(body)
  console.log('Получили:', event.event, event.invoice.invoiceNumber)

  // ⚠️ Отвечайте 200 OK сразу — обрабатывайте асинхронно
  res.status(200).end('ok')
  queue.add('process-lovepay', event)
})

Доставка и retry

Наш бэк отправляет вебхук сразу при событии. Таймаут — 10 секунд. Если получили не 2xx или request упал, делаем повторы по экспоненте:

Попытка	Через
1	сразу
2	+1 минуту
3	+5 минут
4	+15 минут
5	+1 час
6	+4 часа

После 6-й неуспешной попытки вебхук помечается как failed, но можно вручную перепослать через «История доставки» в карточке вебхука.

Идемпотентность. Один и тот же X-LNP-Delivery UUID может прийти повторно при ретраях. Сохраняйте обработанные delivery-id в БД и игнорируйте дубли.

Best practices

• Отвечайте 200 OK немедленно. Обработку (письма клиенту, обновление БД) делайте асинхронно в очереди. Если ответите долго — у вас таймаут, у нас ретрай.
• Только HTTPS в production. HTTP вебхуки технически работают, но Cloudflare/Mintlify-провайдеры могут блокировать.
• Логируйте X-LNP-Delivery во всех своих логах — пригодится при разборе спорных случаев с поддержкой.
• Проверяйте signature ВСЕГДА, не верьте даже если IP белый.
• Замена секрета: в кабинете есть «Сгенерировать новый секрет» — старый перестаёт работать сразу, обновите его на своей стороне без даунтайма.

История и отладка

В кабинете в Вебхуки → история доставки видно:

• Время отправки и попыток
• HTTP-статус ответа
• Тело ответа (первые 1 КБ)
• Возможность повторить вручную

FAQ

Можно ли создавать вебхуки через API?

Нет. Только через веб-кабинет. Это политика безопасности — чтобы скомпрометированный API-ключ не позволил атакующему перенаправить ваши финансовые уведомления.

Куда придёт webhook если URL временно недоступен?

Будем повторять до 6 раз с возрастающим интервалом (см. таблицу выше). Все попытки видны в истории доставки.

Можно ли иметь несколько вебхуков?

Да. Можно создать N вебхуков на разные URL и разные наборы событий — например, один для production, второй для staging.

Что отвечать если события не нужно обрабатывать?

Любой 2xx ответ считается успешным. Если конкретное событие не интересно — просто верните 200 без обработки.

Есть тестовый webhook для разработки?

Используйте кнопку «Тест» в карточке вебхука — отправит примерный payload на ваш URL. Или подключите webhook.site для отладки.