Перейти к основному содержимому

Webhooks API

Система webhook-уведомлений для интеграции с внешними сервисами.

Обзор​

Webhooks позволяют получать уведомления о важных событиях в режиме реального времени без необходимости постоянного опроса API.

Поддерживаемые события​

Заказы​

  • order.created - Создан новый заказ
  • order.status_changed - Изменен статус заказа
  • order.cancelled - Заказ отменен
  • order.completed - Заказ выполнен

Платежи​

  • payment.succeeded - Успешная оплата
  • payment.failed - Ошибка оплаты
  • payment.refunded - Возврат платежа

Товары​

  • product.created - Добавлен новый товар
  • product.updated - Обновлен товар
  • product.out_of_stock - Товар закончился

Пользователи​

  • user.registered - Регистрация нового пользователя
  • user.verified - Подтверждение email

Настройка webhook​

// POST /api/webhooks
{
  "url": "https://your-domain.com/webhook",
  "events": ["order.created", "payment.succeeded"],
  "secret": "your-secret-key",
  "active": true
}

Структура webhook-запроса​

// Headers
{
  "Content-Type": "application/json",
  "X-Webhook-Signature": "sha256=...",
  "X-Webhook-Event": "order.created",
  "X-Webhook-ID": "uuid"
}

// Body
{
  "event": "order.created",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "order": {
      "id": "uuid",
      "status": "pending",
      "total": 5000,
      // ... остальные поля заказа
    }
  }
}

Проверка подписи​

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const digest = `sha256=${hmac.digest('hex')}`;
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Повторные попытки​

Система автоматически повторяет отправку webhook при ошибках:

  • 1-я попытка: немедленно
  • 2-я попытка: через 1 минуту
  • 3-я попытка: через 5 минут
  • 4-я попытка: через 15 минут
  • 5-я попытка: через 1 час

Тестирование webhooks​

// POST /api/webhooks/{id}/test
{
  "event": "order.created"
}

Ответ:

{
  "success": true,
  "response_code": 200,
  "response_time": 245,
  "error": null
}

Логи webhooks​

// GET /api/webhooks/{id}/logs
{
  "logs": [
    {
      "id": "uuid",
      "event": "order.created",
      "status": "success",
      "response_code": 200,
      "attempts": 1,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Безопасность​

  • Всегда проверяйте подпись webhook
  • Используйте HTTPS для URL webhooks
  • Ограничивайте доступ к endpoint-у webhook
  • Храните secret в безопасном месте