Вебхуки

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

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

Настройка

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

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

Через API

Установить URL вебхука (возвращает секрет один раз):

bash
curl -X POST "https://api.fazercards.com/api/v1/me/webhook" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-server.com/webhook"}'

События

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

СтатусКогда срабатывает
completedЗаказ выполнен — коды доставлены
refundedЗаказ возвращён
failedЗаказ не выполнен или ошибка

Формат payload

Каждый запрос вебхука — JSON объект:

Поля payload: event — всегда order.status_changed; timestamp — ISO 8601; data — order_id, status, type, amount_charged, currency, product_name, codes (массив, пустой для failed/refunded), created_at, updated_at.

json
{
  "event": "order.status_changed",
  "timestamp": "2026-03-14T12:34:56.789Z",
  "data": {
    "order_id": "ord_xxx",
    "status": "completed",
    "type": "gift_card",
    "amount_charged": 5.00,
    "currency": "USDT",
    "product_id": "prod_xxx",
    "product_name": "Steam $10",
    "codes": ["XXXX-YYYY-ZZZZ"],
    "created_at": "2026-03-14T12:00:00Z",
    "updated_at": "2026-03-14T12:34:56Z"
  }
}

Для completed — codes содержит коды. Для refunded/failed — codes пустой.

Пример failed заказа

json
{
  "event": "order.status_changed",
  "timestamp": "2026-03-14T12:34:56.789Z",
  "data": {
    "order_id": "ord_xxx",
    "status": "failed",
    "type": "gift_card",
    "amount_charged": 5.00,
    "currency": "USDT",
    "product_name": "Steam $10",
    "codes": [],
    "created_at": "2026-03-14T12:00:00Z",
    "updated_at": "2026-03-14T12:34:56Z"
  }
}

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

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

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

Если нужно сменить секрет (например, после утечки):

bash
curl -X POST "https://api.fazercards.com/api/v1/me/webhook/regenerate" \
  -H "X-API-Key: YOUR_API_KEY"

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

Повторов нет. Fire-and-forget. Эндпоинт должен вернуть 200 в течение ~5 сек.

Рекомендации по безопасности

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

API эндпоинты вебхука

GET/me/webhook

Get current webhook config

POST/me/webhook

Set webhook URL (returns secret once)

PUT/me/webhook/settings

Update webhook URL

POST/me/webhook/regenerate

Regenerate secret (returns new secret once)

DELETE/me/webhook

Remove webhook

POST/me/webhook/test

Send a test event