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

> Разбираем, как вебхуки Baserow уведомляют внешние сервисы о строках, представлениях и полях: настройка, структура payload и повторные попытки при сбоях.

Source: https://opennix.org/docs/baserow/webhook-api/webhooks/


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

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

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

Когда вы создаёте, изменяете или удаляете данные в Baserow, вебхук мгновенно уведомляет выбранный эндпоинт с подробной информацией о том, что изменилось. Это позволяет строить интеграции с другими инструментами, автоматизированные цепочки действий и синхронизацию данных в реальном времени без постоянного опроса [REST API базы данных](/docs/baserow/webhook-api/database-api/).

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

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

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

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

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

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

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

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

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

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

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

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

![Диалог создания вебхука Baserow с выбором HTTP-метода, URL и событий-триггеров](/images/baserow/webhook-api/webhooks-create-webhook-dialog.jpg)

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

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

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

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

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

```json
{
    "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 со статусом последнего вызова и кнопкой подробностей](/images/baserow/webhook-api/webhooks-edit-webhook-dialog.png)

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

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

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

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

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

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

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

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

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

**Как узнать, какой пользователь вызвал событие вебхука?** Чтобы включить информацию о пользователе в payload, добавьте в таблицу поле [«Кем изменено»](/docs/baserow/field-types/last-modified-by-field/). Вебхук отправляет полные данные изменённой строки, поэтому значение этого поля автоматически попадёт в payload и укажет, какой пользователь внёс последнее изменение.

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

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

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

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

**Можно ли использовать вебхуки вместе с внешними инструментами автоматизации?** Да, вебхуки работают с [Zapier](/docs/baserow/integrations/zapier/), [Make](/docs/baserow/integrations/make/), [n8n](/docs/baserow/integrations/n8n/) и другими платформами автоматизации - достаточно указать в качестве эндпоинта URL вебхука, который выдаёт инструмент автоматизации.

Далее - [«Персональные токены доступа»](/docs/baserow/webhook-api/personal-api-tokens/): как получить токен для прямых запросов к REST API без вебхуков.