Вебхуки

SDK предоставляет методы для работы с вебхуками, позволяя интегрировать ваше приложение с внешними сервисами и автоматизацией EMD Cloud.

Что такое вебхуки?

Вебхуки — это HTTP callback'и, которые позволяют вашему приложению получать уведомления о событиях в реальном времени. Вместо постоянных запросов к API, сервер отправляет данные на указанный URL при возникновении события.

Использование вебхуков

Триггер вебхука

Вы можете вызвать вебхук из вашего приложения для запуска автоматизации или отправки данных на внешний сервис.

await emdCloud.webhook.trigger(webhookId, data);

Параметры

Параметр	Тип	Описание
webhookId	string	ID вебхука в EMD Cloud
data	object	Данные для отправки

Примеры

Отправка данных формы:

async function submitForm(formData) {
  try {
    const result = await emdCloud.webhook.trigger('webhook-id-123', {
      name: formData.name,
      email: formData.email,
      message: formData.message,
      timestamp: new Date().toISOString()
    });
    
    console.log('Данные отправлены:', result);
    return result;
    
  } catch (error) {
    console.error('Ошибка отправки:', error);
    throw error;
  }
}

Уведомление о событии:

// Отправить уведомление о новом заказе
await emdCloud.webhook.trigger('new-order-webhook', {
  orderId: order.id,
  customer: order.customer,
  total: order.total,
  items: order.items
});

Интеграция с внешним сервисом:

// Отправить данные в CRM
async function syncToСRM(userData) {
  await emdCloud.webhook.trigger('crm-sync-webhook', {
    action: 'create_contact',
    contact: {
      firstName: userData.firstName,
      lastName: userData.lastName,
      email: userData.email,
      phone: userData.phone,
      company: userData.company
    }
  });
}

Интеграция с автоматизацией

Вебхуки часто используются для запуска сценариев автоматизации в EMD Cloud:

// Запустить сценарий обработки заказа
async function processOrder(orderId) {
  await emdCloud.webhook.trigger('process-order-webhook', {
    orderId: orderId,
    action: 'process',
    priority: 'high'
  });
}

// Запустить сценарий отправки email
async function sendWelcomeEmail(userId) {
  await emdCloud.webhook.trigger('welcome-email-webhook', {
    userId: userId,
    template: 'welcome',
    language: 'ru'
  });
}

Обработка входящих вебхуков

Если вы настроили вебхук для получения данных от EMD Cloud, вот пример обработки на сервере:

Node.js + Express

const express = require('express');
const app = express();

app.use(express.json());

// Endpoint для получения вебхуков
app.post('/webhooks/emd-cloud', async (req, res) => {
  try {
    const data = req.body;
    
    console.log('Получен вебхук:', data);
    
    // Обработка данных
    switch (data.event) {
      case 'user.created':
        await handleUserCreated(data.user);
        break;
        
      case 'order.completed':
        await handleOrderCompleted(data.order);
        break;
        
      case 'payment.received':
        await handlePaymentReceived(data.payment);
        break;
        
      default:
        console.log('Неизвестное событие:', data.event);
    }
    
    // Отправляем подтверждение
    res.status(200).json({ success: true });
    
  } catch (error) {
    console.error('Ошибка обработки вебхука:', error);
    res.status(500).json({ error: error.message });
  }
});

async function handleUserCreated(user) {
  console.log('Новый пользователь:', user.email);
  // Ваша логика
}

async function handleOrderCompleted(order) {
  console.log('Заказ завершен:', order.id);
  // Ваша логика
}

async function handlePaymentReceived(payment) {
  console.log('Платеж получен:', payment.amount);
  // Ваша логика
}

app.listen(3000, () => {
  console.log('Сервер запущен на порту 3000');
});

Безопасность вебхуков

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

Для защиты от поддельных запросов рекомендуется проверять подпись вебхука:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return signature === expectedSignature;
}

app.post('/webhooks/emd-cloud', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Обработка вебхука
  // ...
});

Идемпотентность

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

const processedWebhooks = new Set();

app.post('/webhooks/emd-cloud', async (req, res) => {
  const webhookId = req.body.id;
  
  // Проверяем, не обрабатывали ли мы уже этот вебхук
  if (processedWebhooks.has(webhookId)) {
    console.log('Вебхук уже обработан:', webhookId);
    return res.status(200).json({ success: true });
  }
  
  // Обрабатываем вебхук
  await processWebhook(req.body);
  
  // Сохраняем ID обработанного вебхука
  processedWebhooks.add(webhookId);
  
  res.status(200).json({ success: true });
});

Примеры использования

Отправка уведомлений

// Отправить уведомление в Telegram
async function sendTelegramNotification(message) {
  await emdCloud.webhook.trigger('telegram-webhook', {
    chat_id: process.env.TELEGRAM_CHAT_ID,
    text: message
  });
}

// Отправить уведомление в Slack
async function sendSlackNotification(message) {
  await emdCloud.webhook.trigger('slack-webhook', {
    channel: '#notifications',
    text: message,
    username: 'EMD Cloud Bot'
  });
}

Синхронизация данных

// Синхронизация пользователя с внешней системой
async function syncUserToExternalSystem(user) {
  await emdCloud.webhook.trigger('external-sync-webhook', {
    action: 'sync_user',
    user: {
      id: user.id,
      email: user.email,
      name: user.name,
      createdAt: user.createdAt
    }
  });
}

Обработка платежей

// Уведомление о новом платеже
async function notifyPaymentReceived(payment) {
  await emdCloud.webhook.trigger('payment-webhook', {
    event: 'payment.received',
    payment: {
      id: payment.id,
      amount: payment.amount,
      currency: payment.currency,
      userId: payment.userId,
      status: payment.status
    }
  });
}

Best Practices

Асинхронная обработка

// ✅ Хорошо: быстро отвечаем и обрабатываем асинхронно
app.post('/webhooks/emd-cloud', async (req, res) => {
  // Сразу отправляем ответ
  res.status(200).json({ success: true });
  
  // Обрабатываем асинхронно
  processWebhookAsync(req.body).catch(error => {
    console.error('Ошибка обработки:', error);
  });
});

async function processWebhookAsync(data) {
  // Долгая обработка
  await performHeavyOperation(data);
}

Логирование

// ✅ Хорошо: логируем все вебхуки для отладки
app.post('/webhooks/emd-cloud', async (req, res) => {
  const webhookId = req.body.id;
  
  console.log('Получен вебхук:', {
    id: webhookId,
    event: req.body.event,
    timestamp: new Date().toISOString()
  });
  
  try {
    await processWebhook(req.body);
    console.log('Вебхук обработан успешно:', webhookId);
  } catch (error) {
    console.error('Ошибка обработки вебхука:', webhookId, error);
  }
  
  res.status(200).json({ success: true });
});

Retry логика

// ✅ Хорошо: повторяем при ошибках
async function triggerWebhookWithRetry(webhookId, data, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await emdCloud.webhook.trigger(webhookId, data);
      return result;
    } catch (error) {
      console.error(`Попытка ${attempt} не удалась:`, error);
      
      if (attempt === maxRetries) {
        throw error;
      }
      
      // Экспоненциальная задержка
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, attempt) * 1000)
      );
    }
  }
}

Следующие шаги

• 🔄 Узнайте об автоматизации
• ⚛️ Изучите React хуки для вебхуков
• 💡 Посмотрите примеры интеграций

Полезные ссылки

• Раздел Автоматизация
• API документация
• GitHub репозиторий