Вебхуки, колбэки и идемпотентность в платежных API

Получить CloudPayments бесплатно

Вебхуки, колбэки и идемпотентность в платежных API

Table of contents

Что такое вебхуки в платежах и чем они лучше поллинга

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

Основные преимущества:

Сравнение подходов:

Параметр Вебхуки Поллинг
Задержка Низкая, почти реальное время Зависит от интервала опроса
Нагрузка Низкая на ваш сервер и на API провайдера Может быть высокой при большом количестве платежей
Сложность Требуется публичная endpoint и безопасность Проще стартовать, но хуже UX
Надежность Требуются ретраи вебхуков и подпись Требуется очередь повторов опроса

Для стартовой картины интеграции см. также базовые принципы.

Архитектура: очереди событий и обработчики

Надежная обработка колбэков платежей строится вокруг очереди событий, идемпотентных хендлеров и мониторинга.

Рекомендуемый поток:

  1. Платежный провайдер отправляет POST вебхук на ваш публичный endpoint (например, /webhooks/payments).
  2. Вы проверяете подпись вебхуков, валидируете схему и timestamp.
  3. Сырые события складываете в очередь (очереди событий: Kafka, RabbitMQ, SQS) или в таблицу входящих уведомлений.
  4. Идемпотентный воркер обрабатывает событие: обновляет статус платежа, записывает журнал, инициирует последующие действия (e‑mail, доступ, отгрузка).
  5. На время обработки возвращаете 200 OK как можно раньше, чтобы не провоцировать лишние повторы со стороны провайдера.

Использование очереди снимает спайки нагрузки и изолирует внешний трафик от бизнес-логики. Для сверки итогов интегрируйте фоновый процесс с реестрами и отчетами.

Подпись вебхуков и безопасность

Подпись вебхуков — ключ к защите от подмены и повторного воспроизведения событий. Типичные элементы:

Пример валидации HMAC-SHA256 (Node.js, псевдо):

import crypto from 'crypto';

function verifyWebhook({ rawBody, signatureHeader, timestampHeader, secret }) {
  const ts = parseInt(timestampHeader, 10);
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false; // окно 5 минут
  const message = `${ts}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  // Сравнение в константное время
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Минимум, который стоит внедрить:

О базовых требованиях и 3‑D Secure см. раздел безопасности.

Ретраи вебхуков и гарантии доставки

Ни один канал доставки не идеален. Провайдеры выполняют ретраи вебхуков при таймаутах или кодах 5xx. Ваша задача — сделать обработку повторов корректной.

Практики:

Если входящий webhook обрабатывается долго, лучше подтверждать приём (202/200) и продолжать асинхронно в воркере. Это снижает риск повторов.

Idempotency в платежных API: зачем и как

Idempotency API обеспечивает, что повтор одного и того же запроса (например, списание, возврат) не приведет к повторной операции. Это критично при сетевых сбоях, ретраях клиента и браузерных «обновить страницу».

Базовая модель:

Пример серверной логики (псевдо, SQL + кэш):

def charge(idempotency_key, payload):
    row = db.get("SELECT status, response FROM idem WHERE key = %s", [idempotency_key])
    if row and row.status == 'DONE':
        return row.response  # тот же ответ
    if row and row.status == 'IN_PROGRESS':
        raise RetryLater()   # 409/202, подождать

    db.insert("INSERT INTO idem(key, status) VALUES(%s,'IN_PROGRESS')", [idempotency_key])
    try:
        resp = provider.charge(payload)
        db.update("UPDATE idem SET status='DONE', response=%s WHERE key=%s", [resp, idempotency_key])
        return resp
    except Exception as e:
        db.update("UPDATE idem SET status='FAILED' WHERE key=%s", [idempotency_key])
        raise e

Рекомендации по идемпотентным операциям:

Подробнее про возвраты и отмены — в разделе refunds & reversals.

Пайплайн обработки колбэков платежей

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

Шаги «золотого» пути:

  1. Примите запрос: ограничьте размер тела, читайте raw body для подписи.
  2. Проверьте TLS, IP allowlist (если доступно), заголовки timestamp и подписи.
  3. Валидация схемы события и известности event_type.
  4. Дедупликация по event_id (или Idempotency-Key, если он в webhook-е).
  5. Сохраните событие в очереди/таблице (status = received).
  6. Немедленно ответьте 200 OK.
  7. В воркере: идемпотентно обновите статус платежа, создайте доменную запись (order paid), запишите аудит.
  8. Публикуйте внутренние события (order.paid) и уведомления пользователям.
  9. Для «тяжелых» действий (отгрузка, интеграции) используйте отдельные очереди.

Пример ответов:

Статусы, возвраты и рекуррентные списания

Жизненный цикл платежа распределён: авторизация может стать «капчером», возврат — частичным, рекуррентные — получат свои вебхуки. Для полной картины:

Особенности интеграции с разными провайдерами

Различия касаются формата событий, заголовков подписи и SLA ретраев. Обзор и практики:

Перед выбором провайдера оцените SLA вебхуков, возможности подписи, наличие тестовой среды и качество документации. Сравнение подходов банков и агрегаторов — в разделе банки vs агрегаторы.

Тестирование и песочницы

Для безопасной отладки используйте песочницы и туннели:

Где это доступно, используйте песочницу провайдера: фиктивные карты, имитация 3‑DS, отклонений, возвратов.

Мониторинг и отладка

Наблюдаемость — основа надежности цепочки вебхуков:

См. практики и готовые чек-листы в разделе ошибки и мониторинг.

Чек-лист безопасности (PCI DSS, 3‑DS)

Подробно — в PCI и 3‑DS.

Частые ошибки и как их избегать

Итоги и что дальше

Надежные вебхуки и idempotency API — фундамент платежной интеграции. Подпись вебхуков, очереди событий, ретраи и идемпотентные операции уменьшают потери, исключают дубликаты и ускоряют бизнес-процессы. Постройте пайплайн «валидация → очередь → идемпотентная обработка → аудит → оповещение», протестируйте в песочнице и включите мониторинг.

Готовы внедрять? Начните с основ интеграции, сравните провайдеров в банки vs агрегаторы и проверьте окружение в песочнице. Если нужны периодические списания — обратитесь к рекуррентным платежам, а для возвратов — к refunds & reversals. Удачной интеграции!

Получить CloudPayments бесплатно