Webhooks

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

Типы событий

Событие	Описание
`deal.created`	Создана новая сделка
`deal.updated`	Обновлена сделка
`deal.status_changed`	Изменен статус сделки
`deal.deleted`	Удалена сделка
`contact.created`	Создан новый контакт
`contact.updated`	Обновлен контакт
`task.created`	Создана задача
`task.completed`	Выполнена задача
`scenario.executed`	Выполнен сценарий
`agent.triggered`	Сработал агент

Создание вебхука

http

POST https://api.neurocall.ai/v1/webhooks
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "url": "https://your-app.com/webhook",
  "events": ["deal.created", "deal.status_changed"],
  "active": true,
  "secret": "your_webhook_secret"
}

Формат уведомления

json

{
  "event": "deal.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "webhook_id": "wh_123456789",
  "data": {
    "id": 12345,
    "name": "Новая сделка",
    "status_id": 142,
    "pipeline_id": 1234,
    "responsible_user_id": 567,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "_links": {
      "self": "https://api.neurocall.ai/v1/deals/12345"
    }
  }
}

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

Для проверки подлинности уведомления используйте секрет:

javascript

// Проверка подписи на Node.js
const crypto = require('crypto');

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

Важно

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

Ответ на вебхук

Ваш endpoint должен вернуть HTTP 200 в течение 5 секунд. При ошибке или таймауте будет 3 попытки повтора с экспоненциальной задержкой.

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

Попытка	Задержка
1	Немедленно
2	5 секунд
3	25 секунд

Управление вебхуками

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

http

GET https://api.neurocall.ai/v1/webhooks
Authorization: Bearer YOUR_TOKEN

Обновление вебхука

http

PATCH https://api.neurocall.ai/v1/webhooks/{webhook_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "events": ["deal.created"],
  "active": false
}

Удаление вебхука

http

DELETE https://api.neurocall.ai/v1/webhooks/{webhook_id}
Authorization: Bearer YOUR_TOKEN

Лучшая практика

При получении вебхука сразу сохраните его в очередь и верните 200. Обработку выполняйте асинхронно, чтобы не превысить таймаут.