Документация
Baserow
Вебхуки и API
Вебхуки

Вебхуки Baserow: настройка событий, payload и повторов

Вебхук Baserow - это HTTP-запрос, который база данных сама отправляет на указанный URL при наступлении события: создании, изменении или удалении строки, а также при изменении представлений и полей; вместо постоянного опроса API внешний сервис получает уведомление мгновенно, с полными данными об изменении в теле запроса.

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

Вебхуки - это автоматические уведомления, которые Baserow отправляет внешним приложениям при наступлении определённых событий в базе данных. Вместо постоянной проверки изменений вручную внешние системы получают обновления в реальном времени.

Когда вы создаёте, изменяете или удаляете данные в Baserow, вебхук мгновенно уведомляет выбранный эндпоинт с подробной информацией о том, что изменилось. Это позволяет строить интеграции с другими инструментами, автоматизированные цепочки действий и синхронизацию данных в реальном времени без постоянного опроса REST API базы данных .

В официальной документации Baserow отмечается, что у каждого вебхука есть очередь ожидающих вызовов вместимостью до 5 000 записей (это значение указано для облачной версии; для self-hosted инсталляции фактический предел зависит от конфигурации сервера) - вызовы сверх лимита отбрасываются, а сама очередь обрабатывается по одному вызову за раз.

Типы событий вебхука

Baserow поддерживает несколько категорий событий, которые можно выбрать при настройке вебхука.

События строк

  • Строки созданы - срабатывает при добавлении новых строк.
  • Строки обновлены - срабатывает при изменении существующих строк.
  • Строки удалены - срабатывает при удалении строк.

События представлений

  • Представление создано - срабатывает при добавлении нового представления.
  • Представление обновлено - срабатывает при изменении настроек представления.
  • Представление удалено - срабатывает при удалении представления.

События полей

  • Поле создано - срабатывает при добавлении нового поля.
  • Поле обновлено - срабатывает при изменении свойств поля.
  • Поле удалено - срабатывает при удалении поля.

Дополнительные события

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

Если вы используете устаревшие типы событий (row.created, row.updated, row.deleted), перейдите на новые пакетные типы (rows.created, rows.updated, rows.deleted) - они работают эффективнее при массовых изменениях.

Диалог создания вебхука Baserow с выбором HTTP-метода, URL и событий-триггеров

Как создать вебхук

  1. Откройте настройки вебхуков
    • Нажмите значок ⋮ рядом с именем таблицы или представления в боковой панели.
    • Выберите Вебхуки в меню.
    • Нажмите Создать вебхук +.
  2. Настройте основные параметры
    • Введите понятное название вебхука.
    • Выберите HTTP-метод (GET, POST, PUT, PATCH, DELETE).
    • Укажите целевой URL-адрес эндпоинта.
  3. Выберите события-триггеры
    • Отметьте «Отправлять все события», чтобы подписаться на все типы событий.
    • Либо выберите только нужные события вручную.
  4. Добавьте дополнительные заголовки (опционально)
    • Укажите токены авторизации.
    • Задайте Content-Type или другие необходимые заголовки.
  5. Протестируйте вебхук
    • Нажмите Отправить тестовый вебхук.
    • Убедитесь, что эндпоинт получил тестовый payload.
    • Проверьте ответ прямо в Baserow.
  6. Сохраните и активируйте
    • Нажмите Сохранить, чтобы включить вебхук.
    • Проверьте работу на реальных действиях в таблице.

Структура payload вебхука

Baserow отправляет структурированный payload в формате JSON, который содержит сведения о событии и данные затронутой записи.

Пример payload для события «Представление создано»:

{
    "table_id": 50000,
    "database_id": 1000,
    "workspace_id": 300,
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "view.created",
    "view": {
        "id": 0,
        "table_id": 0,
        "name": "View",
        "order": 1,
        "type": "grid",
        "table": null,
        "filter_type": "AND",
        "filters_disabled": false,
        "public_view_has_password": false,
        "show_logo": true,
        "ownership_type": "collaborative",
        "owned_by_id": null,
        "row_identifier_type": "id",
        "public": false
    }
}

Ключевые элементы payload:

  • Идентификаторы: table_id, database_id, workspace_id указывают источник события.
  • Информация о событии: event_type и event_id описывают, что именно произошло.
  • Объект данных: содержит полные сведения об изменённом объекте - строке, представлении или поле.

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

Редактирование вебхука

  1. Откройте настройки вебхуков через значок ⋮ у таблицы.
  2. Нажмите Подробнее рядом с нужным вебхуком.
  3. Выберите Редактировать.
  4. Измените нужные параметры.
  5. Нажмите Сохранить.

Окно управления вебхуком Baserow со статусом последнего вызова и кнопкой подробностей

Мониторинг вызовов вебхука

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

  1. Откройте подробности вебхука.
  2. Выберите вкладку Журнал вызовов.
  3. Изучите детали запроса и ответа для каждого вызова.

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

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

Обработка ошибок и надёжность

Baserow автоматически повторяет неудачные вызовы вебхука:

  • Количество попыток: ограниченное число повторов для каждого неуспешного вызова.
  • Критерий успеха: эндпоинт должен вернуть статус 200 OK.
  • Рекомендация: эндпоинт должен быть надёжным и выдерживать всплески нагрузки при массовых изменениях данных.

Часто задаваемые вопросы

Как узнать, какой пользователь вызвал событие вебхука? Чтобы включить информацию о пользователе в payload, добавьте в таблицу поле «Кем изменено» . Вебхук отправляет полные данные изменённой строки, поэтому значение этого поля автоматически попадёт в payload и укажет, какой пользователь внёс последнее изменение.

Что произойдёт, если эндпоинт вебхука недоступен? Baserow автоматически повторяет неудачные вызовы ограниченное число раз. Убедитесь, что эндпоинт возвращает статус 200 OK и способен выдержать временные всплески нагрузки.

Можно ли фильтровать, какие строки вызывают вебхук? Да, используйте условное обновление строки, чтобы вебхук срабатывал только при изменении значений определённых полей. Также подойдёт вебхук на основе представления - он срабатывает только для строк, соответствующих фильтрам этого представления.

Как найти причину сбоя вебхука? Проверьте журнал вызовов в Baserow, чтобы увидеть детали запроса и ответа. Частые причины - неверный URL, отсутствующие заголовки авторизации или эндпоинт, не возвращающий статус 200 OK.

Есть ли ограничения по частоте вызовов вебхуков? Baserow не устанавливает жёстких ограничений по частоте, но принимающий эндпоинт должен выдерживать объём изменений в базе данных. Рассмотрите пакетную обработку, если вносится много одновременных изменений.

Можно ли использовать вебхуки вместе с внешними инструментами автоматизации? Да, вебхуки работают с Zapier , Make , n8n и другими платформами автоматизации - достаточно указать в качестве эндпоинта URL вебхука, который выдаёт инструмент автоматизации.

Далее - «Персональные токены доступа» : как получить токен для прямых запросов к REST API без вебхуков.

Проверено OpenNix LLC · Обновлено
Вебхуки и APIТокены API базы данных