Вебхуки

Получайте уведомления в реальном времени при изменении статуса заказа. Подписанные JSON, простая верификация.

Вебхук — это HTTP-коллбэк: когда статус заказа меняется, мы отправляем POST-запрос на ваш URL с данными события. Не нужен поллинг — вы получаете мгновенные уведомления.

Настройка

Через панель реселлера

Откройте Настройки → Webhook, введите URL (https:// или http://), сохраните. Секрет создаётся автоматически и отображается в этом же разделе — храните его в безопасном месте. По кнопке можно ротировать секрет (старый сразу перестаёт работать) и отправить тестовый запрос.

Публичный API v2

Управление вебхуком доступно через API: GET/PUT /api/v2/account/webhook (URL + enabled), POST /api/v2/account/webhook/secret/regenerate, POST /api/v2/account/webhook/test, GET /api/v2/account/webhook/deliveries. Авторизация — X-API-Key или Authorization: Bearer.

api.fzr.cards/public/docs

События

Вебхук получает несколько типов событий по всем заказам аккаунта. Дополнительная настройка не требуется — все события включены при настроенном URL.

СобытиеКогда срабатывает
order.createdorder.created — создан заказ (любой тип, включая API и панельные)
order.status_changedorder.status_changed — изменился статус заказа (processing → completed/failed/refunded/…)
manual_service.chat.*manual_service.chat.message — новое сообщение от поставщика в чате ручной услуги; manual_service.chat.waiting_reply — поставщик ждёт ответа клиента

Формат данных

docs.webhooks.payloadDesc

docs.webhooks.payloadFields

json
{
  "event": "order.status_changed",
  "event_id": "8f3a2c9e-1b4d-4f7a-9e2c-5b6a8c1d2e3f",
  "timestamp": "2026-03-14T12:34:56.789Z",
  "data": {
    "order_id": "ord-1001",
    "type": "giftcard",
    "status": "completed",
    "previous_status": "processing"
  }
}

docs.webhooks.completedPayloadNote

Пример события чата ручной услуги

json
{
  "event": "manual_service.chat.message",
  "event_id": "1d2c3b4a-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "timestamp": "2026-03-14T12:34:56.789Z",
  "data": {
    "order_id": "ord-1002",
    "type": "manual",
    "message_preview": "Hi! Could you confirm the recipient handle?",
    "message_created_at": "2026-03-14T12:34:55Z"
  }
}

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

docs.webhooks.signatureDesc

Подпись доказывает, что запрос пришёл от FazerCards. Без проверки злоумышленник может подделать вебхук.

Пример Node.js

javascript
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'utf8'),
    Buffer.from(expected, 'utf8')
  );
}

// Usage (Express)
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-webhook-signature'];
  if (!verifyWebhookSignature(req.body.toString(), sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const payload = JSON.parse(req.body.toString());
  // Process payload...
  res.status(200).send('OK');
});

Пример Python

python
import hmac
import hashlib

def verify_webhook_signature(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Usage (Flask)
@app.route('/webhook', methods=['POST'])
def webhook():
    raw_body = request.get_data()
    sig = request.headers.get('X-Webhook-Signature', '')
    if not verify_webhook_signature(raw_body, sig, os.environ['WEBHOOK_SECRET']):
        return 'Invalid signature', 401
    payload = request.get_json()
    # Process payload...
    return 'OK', 200

Перегенерация секрета

Через панель в Настройках или через POST /api/v2/account/webhook/secret/regenerate. Старый секрет сразу перестаёт работать — обновите его в вашем приёмнике.

Политика повторов

До 3 повторов с экспоненциальной задержкой (1 минута, 5 минут, 30 минут) при ответах не из 2xx или таймауте 10 с. После 50 подряд неудачных попыток вебхук авто-отключается — включите его повторно в настройках после фикса.

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

  • Всегда проверяйте подпись
  • Используйте HTTPS в продакшене
  • Храните секрет безопасно
  • Отвечайте быстро (200 за секунды); тяжёлую работу выполняйте асинхронно