Руководство по вебхукам

1. Создайте конечную точку вебхука

Сначала создайте в своем приложении конечную точку HTTP, которая сможет получать запросы POST от LicenseChain.

// Express.js Example
app.post('/webhooks/licensechain', async (req, res) => {'{'}
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = JSON.stringify(req.body);
  
  // Verify signature (see Security section)
  if (!verifySignature(payload, signature, timestamp, webhookSecret)) {'{'}
    return res.status(401).send('Invalid signature');
  {'}'}
  
  // Process webhook event
  const event = req.body;
  console.log('Received event:', event.type, event.data);
  
  res.status(200).send('OK');
{'}'});

2. Зарегистрируйте свой вебхук

Используйте API LicenseChain для регистрации конечной точки веб-перехватчика. Вам нужно будет указать URL-адрес и указать, какие события вы хотите получать.

POST /v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://your-app.com/webhooks/licensechain",
  "events": ["license.created", "license.updated", "license.revoked"],
  "secret": "optional-custom-secret"
{'}'}

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

LicenseChain поддерживает следующие события веб-перехватчика:

Подписи вебхуков

Все запросы вебхука включают подпись в X-Webhook-Signature заголовок. Подпись HMAC-SHA256 необработанного тела запроса с использованием секрета вашего веб-перехватчика. Всегда проверяйте, используя сравнение в постоянное время (например. crypto.timingSafeEqual), чтобы предотвратить атаки по времени. Значение заголовка может быть необработанным шестнадцатеричным или sha256= за которым следует шестнадцатеричный; раздеть sha256= префикс перед сравнением шестнадцатеричных буферов, чтобы длины совпадали.

// Node.js Example (constant-time, supports sha256= prefix)
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {'{'}
  if (!payload || !signature || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  const received = String(signature).startsWith('sha256=') ? String(signature).slice(7) : String(signature);
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(received, 'hex');
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
{'}'}

// In your webhook handler (use raw body for payload)
const signature = req.headers['x-webhook-signature'];
const payload = req.rawBody || JSON.stringify(req.body);
if (!verifySignature(payload, signature, webhookSecret)) {'{'}
  return res.status(401).send('Invalid signature');
{'}'}

Заголовки запросов

LicenseChain включает следующие заголовки с каждым запросом веб-перехватчика:

Список всех вебхуков

GET /v1/webhooks?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

Получить подробную информацию о вебхуке

GET /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Обновить вебхук

PUT /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://new-url.com/webhooks",
  "events": ["license.created", "license.updated"]
{'}'}

Удалить вебхук

DELETE /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Отправить тестовый вебхук

Вы можете протестировать конечную точку веб-перехватчика, не дожидаясь реального события:

POST /v1/webhooks/:id/test
Authorization: Bearer YOUR_API_KEY

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

Просмотр журналов веб-перехватчиков

Проверьте статус доставки и ответ для каждого события веб-перехватчика:

GET /v1/webhooks/:id/logs?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

Журналы включают код состояния HTTP, тело ответа и информацию о том, была ли доставка успешной.

✅ Всегда проверяйте подписи

Никогда не обрабатывайте события веб-перехватчика без проверки подписи. Это гарантирует, что запрос исходит от LicenseChain и не был подделан.

✅ Отвечайте быстро

Конечная точка веб-перехватчика должна ответить в течение 5 секунд. Для длительных операций немедленно подтвердите веб-перехватчик и выполните асинхронную обработку.

✅ Справиться с идемпотентностью

Используйте идентификатор события, чтобы предотвратить обработку одного и того же события несколько раз. Сохраняйте идентификаторы обработанных событий и проверяйте их перед обработкой.

✅ Используйте HTTPS

Всегда используйте HTTPS для конечных точек веб-перехватчика, чтобы обеспечить шифрование данных при передаче.

✅ Мониторинг журналов веб-перехватчиков

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

Вебхук не получает события

• • Убедитесь, что URL-адрес вашего веб-перехватчика доступен из Интернета.
• • Убедитесь, что ваша конечная точка возвращает код состояния 2xx.
• • Убедитесь, что события, на которые вы подписаны, действительно происходят.
• • Просматривайте журналы веб-перехватчиков на наличие ошибок доставки.

Проверка подписи не удалась

• • Убедитесь, что вы используете правильный секрет веб-перехватчика.
• • Убедитесь, что вы подписываете именно тело запроса (в виде строки JSON).
• • Убедитесь, что вы используете алгоритм HMAC-SHA256.
• • Убедитесь, что заголовки читаются правильно (с учетом регистра).

Ошибки тайм-аута

• • Оптимизируйте обработчик веб-перехватчика для быстрого реагирования.
• • Перенесите тяжелую обработку в фоновые задачи.
• • Немедленно вернуть 200 OK и обработать асинхронно.