🔔 Вебхуки

Получайте уведомления о событиях в реальном времени через HTTP-вызовы

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

Вебхуки — это способ получать уведомления от InstantBase в реальном времени. Когда происходит определенное событие (например, превышение лимита, новый заказ), мы отправляем HTTP-запрос на ваш указанный URL.

Как работают вебхуки

🔔

Событие

В InstantBase происходит событие

→

📡

HTTP-запрос

POST на ваш endpoint

→

⚙️

Ваша система

Обрабатывает уведомление

→

✅

Ответ 200

Подтверждение получения

Типы вебхуков

Тип	Описание	Когда срабатывает
🔔 event.received	Новое событие	При получении нового события от вашего приложения
💰 order.created	Новый заказ	При создании нового заказа (событие с метаданными is_order)
⚠️ limit.warning	Приближение к лимиту	При достижении 80% и 90% месячного лимита
⛔ limit.exceeded	Превышение лимита	При превышении 100% месячного лимита
👤 customer.created	Новый клиент	При первом появлении нового пользователя
📊 insight.generated	Инсайт	При обнаружении значимых изменений в метриках

Настройка вебхуков

Через личный кабинет

Войдите в личный кабинет InstantBase
Перейдите в раздел Настройки → Вебхуки
Нажмите "Добавить вебхук"
Укажите URL вашего endpoint (например, https://api.ваш-сайт.ru/webhooks/instantbase)
Выберите типы событий, по которым хотите получать уведомления
При необходимости добавьте секретный ключ для подписи запросов
Нажмите "Сохранить"

Через API

POST /api/webhooks/create — создание нового вебхука.

json

{
  "url": "https://api.ваш-сайт.ru/webhooks/instantbase",
  "events": ["order.created", "limit.warning", "limit.exceeded"],
  "secret": "your_webhook_secret",
  "is_active": true
}

Форматы вебхуков

1. Новое событие (event.received)

{ "webhook_id": "whk_12345abcde", "event_type": "event.received", "timestamp": "2026-03-19T15:30:00Z", "data": { "event_id": 12345, "event_name": "purchase", "user_id": "user_123", "anonymous_id": "abc-123-def", "occurred_at": "2026-03-19T15:29:45Z", "properties": { "revenue": 1499.99, "order_id": "ORD-001" }, "metadata": { "is_order": true } } }

2. Новый заказ (order.created)

{ "webhook_id": "whk_12345abcde", "event_type": "order.created", "timestamp": "2026-03-19T15:30:00Z", "data": { "order_id": 12345, "order_number": "ORD-001", "user_id": "user_123", "amount": 1499.99, "currency": "RUB", "items": [ { "product_id": "prod_1", "name": "Футболка", "price": 1999, "quantity": 2 } ], "created_at": "2026-03-19T15:29:45Z", "status": "completed" } }

3. Предупреждение о лимите (limit.warning)

{ "webhook_id": "whk_12345abcde", "event_type": "limit.warning", "timestamp": "2026-03-19T15:30:00Z", "data": { "threshold": 80, "used": 42500, "limit": 50000, "percent": 85, "plan": "base", "reset_date": "2026-04-01" } }

4. Превышение лимита (limit.exceeded)

{ "webhook_id": "whk_12345abcde", "event_type": "limit.exceeded", "timestamp": "2026-03-19T15:30:00Z", "data": { "used": 52300, "limit": 50000, "percent": 104.6, "plan": "base", "blocked_until": "2026-04-01T00:00:00Z", "upgrade_url": "https://app.instantbase.online/profile/billing" } }

5. Новый клиент (customer.created)

{ "webhook_id": "whk_12345abcde", "event_type": "customer.created", "timestamp": "2026-03-19T15:30:00Z", "data": { "customer_id": 10042, "external_id": "user_123", "first_seen": "2026-03-19T15:29:45Z", "attributes": { "email": "user@example.com", "name": "Иван Петров", "source": "google_ads" } } }

6. Инсайт (insight.generated)

{ "webhook_id": "whk_12345abcde", "event_type": "insight.generated", "timestamp": "2026-03-19T15:30:00Z", "data": { "insight_id": "ins_12345", "title": "Рост конверсии", "description": "Конверсия в покупку выросла на 15% за последнюю неделю", "metric": "conversion_rate", "change": 15.2, "period_from": "2026-03-12", "period_to": "2026-03-19", "previous_period": "2026-03-05 - 2026-03-11", "link": "/orders" } }

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

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

Все вебхуки подписываются с использованием секретного ключа. Подпись передается в заголовке X-InstantBase-Signature.

javascript

const crypto = require('crypto');

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

// Использование в Express
app.post('/webhooks/instantbase', (req, res) => {
  const signature = req.headers['x-instantbase-signature'];
  const payload = req.body;
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Обработка вебхука
  console.log('Received webhook:', payload.event_type);
  res.status(200).send('OK');
});

Python пример

python

import hmac
import hashlib
import json
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = b'your_webhook_secret'

def verify_signature(payload, signature):
    expected = hmac.new(
        WEBHOOK_SECRET,
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route('/webhooks/instantbase', methods=['POST'])
def webhook():
    signature = request.headers.get('X-InstantBase-Signature')
    payload = request.json
    
    if not verify_signature(payload, signature):
        abort(401)
    
    print(f"Received webhook: {payload['event_type']}")
    return 'OK', 200

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

Получение списка вебхуков

GET /api/webhooks/list — список всех настроенных вебхуков.

Пример ответа

{
  "success": true,
  "webhooks": [
    {
      "id": 1,
      "url": "https://api.ваш-сайт.ru/webhooks/instantbase",
      "events": ["order.created", "limit.warning"],
      "is_active": true,
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

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

PUT /api/webhooks/update/{id} — обновление существующего вебхука.

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

DELETE /api/webhooks/delete/{id} — удаление вебхука.

Тестирование вебхука

POST /api/webhooks/test/{id} — отправка тестового события для проверки.

Лимиты и надежность

Параметр	Значение
Таймаут запроса	5 секунд
Повторные попытки	3 раза (через 1, 5 и 15 минут)
Максимальный размер	1 МБ
Ожидаемый код ответа	200 OK

⚠️ Важно: Если ваш endpoint не отвечает кодом 200 в течение 5 секунд, мы считаем доставку неуспешной и делаем повторные попытки. После 3 неудачных попыток вебхук временно деактивируется.

Примеры интеграции

Node.js (Express) — полный пример

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

app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

function verifySignature(payload, signature) {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post('/webhooks/instantbase', (req, res) => {
  const signature = req.headers['x-instantbase-signature'];
  const payload = req.body;
  
  if (!verifySignature(payload, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  switch (payload.event_type) {
    case 'order.created':
      console.log('Новый заказ!', payload.data);
      // Отправить уведомление в Telegram
      // Обновить CRM
      break;
      
    case 'limit.warning':
      console.log(`Внимание: использовано ${payload.data.percent}% лимита`);
      // Отправить уведомление менеджеру
      break;
      
    case 'limit.exceeded':
      console.log('Лимит превышен!', payload.data);
      // Заблокировать функционал
      break;
  }
  
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook listener running on port 3000');
});

Python (Flask) — обработка разных типов

from flask import Flask, request, jsonify
import hmac
import hashlib
import json

app = Flask(__name__)
WEBHOOK_SECRET = b'your_webhook_secret'

def verify_signature(payload, signature):
    expected = hmac.new(
        WEBHOOK_SECRET,
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route('/webhooks/instantbase', methods=['POST'])
def webhook():
    signature = request.headers.get('X-InstantBase-Signature')
    payload = request.json
    
    if not verify_signature(payload, signature):
        return jsonify({'error': 'Invalid signature'}), 401
    
    event_type = payload['event_type']
    data = payload['data']
    
    handlers = {
        'order.created': handle_order_created,
        'limit.warning': handle_limit_warning,
        'limit.exceeded': handle_limit_exceeded,
        'customer.created': handle_customer_created,
        'insight.generated': handle_insight
    }
    
    handler = handlers.get(event_type)
    if handler:
        handler(data)
    
    return 'OK', 200

def handle_order_created(data):
    print(f"Новый заказ #{data['order_number']} на сумму {data['amount']}")

def handle_limit_warning(data):
    print(f"Предупреждение: {data['percent']}% лимита")

def handle_limit_exceeded(data):
    print(f"Критично: превышен лимит!")
    
def handle_customer_created(data):
    print(f"Новый клиент: {data['attributes'].get('email')}")
    
def handle_insight(data):
    print(f"Инсайт: {data['title']}")

if __name__ == '__main__':
    app.run(port=3000)

Проверка работоспособности

Для тестирования вебхуков можно использовать сервисы типа webhook.site или RequestBin.

Создайте временный URL на webhook.site
Добавьте этот URL в настройках вебхуков InstantBase
Выберите типы событий для тестирования
Совершите действие, которое должно вызвать вебхук
Проверьте, пришел ли запрос на webhook.site

Коды ошибок

Код	Описание	Решение
400	Invalid webhook configuration	Проверьте URL и список событий
401	Unauthorized	Требуется авторизация
404	Webhook not found	Вебхук с указанным ID не существует
429	Too many webhooks	Превышен лимит количества вебхуков (максимум 10)

Что дальше?

📋 События

Отправка и получение событий

Перейти →

📊 Дашборд

Знакомство с интерфейсом