---
pkg: '@nocobase/plugin-workflow-webhook'
---

# Вебхук

## Введение

Триггер вебхука предоставляет URL-адрес, который может быть вызван сторонними системами с помощью HTTP-запросов. Когда происходит стороннее событие, на этот URL-адрес отправляется HTTP-запрос, запускающий выполнение рабочего процесса. Он подходит для уведомлений, инициируемых внешними системами, например, для обратных вызовов платежей или сообщений.

## Создание рабочего процесса

При создании рабочего процесса выберите тип «Событие вебхука»:

![20241210105049](https://static-docs.nocobase.com/20241210105049.png)

:::info{title="Примечание"}
Разница между «синхронными» и «асинхронными» рабочими процессами заключается в том, что синхронный рабочий процесс ожидает завершения своего выполнения, прежде чем вернуть ответ, тогда как асинхронный рабочий процесс немедленно возвращает ответ, настроенный в триггере, и ставит выполнение в очередь в фоновом режиме.
:::

## Настройка триггера

![20241210105441](https://static-docs.nocobase.com/20241210105441.png)

### URL-адрес вебхука

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

Поддерживается только метод HTTP POST; другие методы вернут ошибку `405`.

### Безопасность

В настоящее время поддерживается базовая аутентификация HTTP. Вы можете включить эту опцию и установить имя пользователя и пароль. Включите имя пользователя и пароль в URL-адрес вебхука в сторонней системе для реализации безопасной аутентификации вебхука (подробнее о стандарте см.: [MDN: HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme)).

Когда установлены имя пользователя и пароль, система проверит, соответствуют ли они данным в запросе. Если они не предоставлены или не совпадают, будет возвращена ошибка `401`.

### Разбор данных запроса

Когда сторонняя система вызывает вебхук, данные, содержащиеся в запросе, необходимо разобрать, прежде чем их можно будет использовать в рабочем процессе. После разбора они становятся переменной триггера, на которую можно ссылаться в последующих узлах.

Разбор HTTP-запроса делится на три части:

1.  Заголовки запроса

    Заголовки запроса обычно представляют собой простые пары «ключ-значение» строкового типа. Поля заголовков, которые вам нужны, можно настроить напрямую, например, `Date`, `X-Request-Id` и т. д.

2.  Параметры запроса

    Параметры запроса — это параметры запроса в URL-адресе, например, параметр `query` в `http://localhost:13000/api/webhook:trigger/1hfmkioou0d?query=1`. Вы можете вставить полный пример URL-адреса или только часть с параметрами запроса и нажать кнопку разбора, чтобы автоматически разобрать пары «ключ-значение».

    ![20241210111155](https://static-docs.nocobase.com/20241210111155.png)

    Автоматический разбор преобразует часть параметров URL-адреса в структуру JSON и генерирует пути, такие как `query[0]`, `query[0].a`, на основе иерархии параметров. Имя пути можно изменить вручную, если оно не соответствует вашим требованиям, но обычно в этом нет необходимости. Псевдоним — это отображаемое имя переменной при её использовании, он является необязательным. Разбор также сгенерирует полный список параметров из примера; вы можете удалить любые параметры, которые вам не нужны.

3.  Тело запроса

    Тело запроса — это часть Body HTTP-запроса. В настоящее время поддерживаются только тела запросов с `Content-Type` `application/json`. Вы можете напрямую настроить пути для разбора или ввести пример JSON и нажать кнопку разбора для автоматического анализа.

    ![20241210112529](https://static-docs.nocobase.com/20241210112529.png)

    Автоматический разбор преобразует пары «ключ-значение» в структуре JSON в пути. Например, `{"a": 1, "b": {"c": 2}}` сгенерирует пути, такие как `a`, `b` и `b.c`. Псевдоним — это отображаемое имя переменной при её использовании, он является необязательным. Разбор также сгенерирует полный список параметров из примера; вы можете удалить любые параметры, которые вам не нужны.

### Настройки ответа

Настройка ответа вебхука различается для синхронных и асинхронных рабочих процессов. Для асинхронных рабочих процессов ответ настраивается непосредственно в триггере. При получении запроса вебхука он немедленно возвращает настроенный ответ сторонней системе, а затем выполняет рабочий процесс. Для синхронных рабочих процессов вам необходимо добавить узел ответа в поток для обработки в соответствии с бизнес-требованиями (подробнее см.: [Узел ответа](#узел-ответа)).

Как правило, ответ на асинхронно запускаемое событие вебхука имеет код состояния `200` и тело ответа `ok`. Вы также можете настроить код состояния ответа, заголовки и тело ответа по мере необходимости.

![20241210114312](https://static-docs.nocobase.com/20241210114312.png)

## Узел ответа

См. также: [Узел ответа](../nodes/response.md)

## Пример

В рабочем процессе вебхука вы можете возвращать различные ответы в зависимости от различных бизнес-условий, как показано на рисунке ниже:

![20241210120655](https://static-docs.nocobase.com/20241210120655.png)

Используйте узел условного ветвления, чтобы определить, соответствует ли определённый бизнес-статус. Если соответствует, верните успешный ответ; в противном случае верните ответ об ошибке.