# Входящие вебхуки

Эта справочная страница описывает публичный приемник для автоматизаций с триггером *Входящий webhook*:

```
POST {webhook_url}
```

Создайте или прочитайте автоматизацию через [REST API](/api-reference/rest.md) и используйте полученный `webhook_url`. URL содержит публичный идентификатор `slug` автоматизации; не конструируйте его из ID автоматизации.

## Аутентификация[​](#authentication "Прямая ссылка на Аутентификация")

Приемник не принимает bearer-токен Just Run. Аутентификацией служит подпись провайдера или общий токен, выбранные через `verifier_type`. Настроенный секрет зашифрован при хранении, никогда не возвращается API и заменяется через `PATCH /v1/automations/{id}`.

Подпись проверяется по точным байтам тела запроса. Не разбирайте и не сериализуйте тело заново перед вычислением HMAC.

| `verifier_type` | Контракт учетных данных                                                                          | Ключ дедупликации                                                          | Тип события                                   |
| --------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------------------------- |
| `generic_hmac`  | Шестнадцатеричная запись HMAC-SHA256 сырого тела строчными буквами в `X-Signature` по умолчанию  | Настроенный заголовок идемпотентности, иначе SHA-256 сырого тела           | Нет                                           |
| `github`        | `X-Hub-Signature-256: sha256=<lowercase hex HMAC-SHA256>`                                        | `X-GitHub-Delivery`, иначе SHA-256 сырого тела                             | `X-GitHub-Event`                              |
| `gitlab`        | `X-Gitlab-Token` равен сохраненному секретному токену                                            | Первый непустой `webhook-id`, `Idempotency-Key`, иначе SHA-256 сырого тела | `X-Gitlab-Event`, иначе `object_kind` из JSON |
| `telegram`      | `X-Telegram-Bot-Api-Secret-Token` совпадает с сохраненным общим секретом                         | Обязательный JSON `update_id`                                              | Первое распознанное поле обновления Telegram  |
| `mattermost`    | `token` в теле, закодированном как форма, или в теле JSON совпадает с сохраненным общим секретом | `trigger_id`, затем `post_id`, иначе SHA-256 сырого тела                   | `trigger_word`, затем `channel_name`          |

Секрет и подпись сравниваются за постоянное время. Отсутствующие и неверные учетные данные намеренно дают одинаковый ответ `401`.

### Настройка GitLab[​](#gitlab-setup "Прямая ссылка на Настройка GitLab")

Используйте `verifier_type: "gitlab"`. В GitLab *Settings* → *Webhooks* укажите *URL* = `webhook_url`, *Secret token* = секрет автоматизации и выберите события. Используйте HTTPS с включенной проверкой SSL. Схема *Signing token* этим верификатором не поддерживается.

Повторы GitLab используют стабильный `webhook-id` (GitLab 19.0+) или `Idempotency-Key` (17.4+). Старые версии GitLab не присылают ни того, ни другого: ключом становится хеш тела, и одинаковые байты тела считаются одним событием. `X-Gitlab-Webhook-UUID` идентифицирует сам вебхук, а не доставку, а `X-Gitlab-Event-UUID` общий у рекурсивных событий; для дедупликации не используется ни один из них. См. [заголовки доставки GitLab](https://docs.gitlab.com/user/project/integrations/webhooks/#delivery-headers).

### Параметры универсального HMAC[​](#generic-hmac-options "Прямая ссылка на Параметры универсального HMAC")

Для `generic_hmac` можно передать объект `verifier_config`:

```
{
  "signature_header": "X-Acme-Signature",
  "prefix": "sha256=",
  "idempotency_header": "X-Acme-Delivery"
}
```

По умолчанию `signature_header` равен `X-Signature`, а `prefix` — пустой строке. Значение подписи состоит из префикса и дайджеста HMAC-SHA256 в строчной шестнадцатеричной записи.

## Отправка события универсального HMAC[​](#send-a-generic-hmac-event "Прямая ссылка на Отправка события универсального HMAC")

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

```
export JUSTRUN_WEBHOOK_URL='https://api.example.com/v1/automations/hooks/replace-me'
export JUSTRUN_WEBHOOK_SECRET='replace-me'

payload='{"hello":"world"}'
signature="$(
  printf '%s' "$payload" |
    openssl dgst -sha256 -hmac "$JUSTRUN_WEBHOOK_SECRET" -hex |
    awk '{print $NF}'
)"

curl --fail-with-body \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "X-Signature: $signature" \
  --data-binary "$payload" \
  "$JUSTRUN_WEBHOOK_URL"
```

В настоящей инсталляции не сохраняйте URL вебхука и секрет в системе контроля версий или истории оболочки.

## Подтверждение и дедупликация[​](#acknowledgement-and-deduplication "Прямая ссылка на Подтверждение и дедупликация")

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

Новая доставка:

```
{
  "run_id": "01900000-0000-7000-8000-000000000000",
  "status": "accepted"
}
```

Повторная доставка:

```
{
  "run_id": "01900000-0000-7000-8000-000000000000",
  "status": "replay"
}
```

Оба ответа имеют статус `202 Accepted`. Повторная доставка не создает второй запуск. Поле `run_id` может быть `null`, если верификатор отклонил событие как повторную доставку до поиска в очереди; иначе оно указывает на существующий запуск.

Дедупликация ограничена одной автоматизацией. У `generic_hmac` без заголовка идемпотентности одинаковые по байтам тела дедуплицируются, потому что ключом становится хеш тела. Настройте стабильный ID доставки провайдера, если одинаковые тела запросов могут быть разными легитимными событиями.

## Что получает действие[​](#what-the-action-receives "Прямая ссылка на Что получает действие")

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

Для действия *HTTP POST* Just Run отправляет `POST` на настроенные порт и путь песочницы со следующими данными:

* точное сырое тело входящего запроса;
* заголовки, перечисленные в `forward_headers`;
* `X-JustRun-Automation` и `X-JustRun-Run`;
* `X-JustRun-Event`, если верификатор извлек тип события.

По умолчанию `forward_headers` содержит `content-type`, `x-github-event`, `x-github-delivery`, `x-gitlab-event`, `x-gitlab-webhook-uuid`, `idempotency-key` и `webhook-id`. Имена приводятся к нижнему регистру. Заголовки аутентификации, аккаунта, хоста, hop-by-hop, `content-length` и пользовательские `x-justrun-*` не пересылаются. Секретные заголовки `x-gitlab-token` и `x-telegram-bot-api-secret-token` не пересылаются и не сохраняются в запуске, даже если перечислены.

Для действия *Выполнить команду* сырое тело передается в стандартный ввод. Just Run добавляет авторитетные переменные окружения `JUSTRUN_*`, включая триггер, запуск, автоматизацию, тип события и ключ дедупликации, когда они доступны.

## Порядок и повторы[​](#ordering-and-retries "Прямая ссылка на Порядок и повторы")

Режим `concurrency_mode` управляет выполнением:

* `parallel` допускает независимые запуски;
* `serial` упорядочивает все запуски одной автоматизации;
* `partitioned` пока доступен только для Telegram и независимо упорядочивает каждую определенную переписку.

Действие *HTTP POST* считается успешным при ответе `2xx`. Ответы не `2xx` и сбои соединения следуют политике повторных попыток запуска. Завершенная команда считается успешной даже при ненулевом коде выхода, если для действия не задано `retry_on_nonzero: true`; сбои инфраструктуры повторяются.

`max_attempts` находится в диапазоне `1..20`; инсталляция по умолчанию задает для автоматизаций с триггером *Входящий webhook* значение `5`. Экспоненциальная задержка и конкурентность обработчика запусков автоматизаций — настройки инсталляции, поэтому клиентам нельзя зависеть от точного времени повтора.

## Лимиты и хранение[​](#limits-and-retention "Прямая ссылка на Лимиты и хранение")

* Лимит входящего тела по умолчанию равен 1 МиБ. Инсталляция может изменить его; слишком большой запрос получает `413`.
* До проверки подписи действует ограничение частоты запросов по IP, а после определения `slug` — по аккаунту.
* Сырые тела вебхуков и выбранные заголовки хранятся согласно `payload_retention_hours` (`1..720`, по умолчанию `24`), после чего удаляются из истории запусков. После удаления тело запроса нельзя отправить повторно вручную.
* Ответ `202` подтверждает постановку в очередь или повторную доставку, но не успех действия. Проверяйте запуск автоматизации через аутентифицированный REST API.

## Ответы[​](#responses "Прямая ссылка на Ответы")

| Статус | Значение                                                                         |
| ------ | -------------------------------------------------------------------------------- |
| `202`  | Событие принято или подтверждено как повторная доставка                          |
| `400`  | Тело запроса провайдера некорректно, например в JSON от Telegram нет `update_id` |
| `401`  | Подпись или общий токен отсутствует либо неверен                                 |
| `403`  | Автоматизация выключена                                                          |
| `404`  | `slug` неизвестен или нет пригодного состояния верификатора вебхука              |
| `413`  | Тело превышает лимит входящего вебхука в инсталляции                             |
| `422`  | Автоматизация не привязана к песочнице                                           |
| `429`  | Превышено ограничение частоты запросов по IP или по аккаунту                     |
| `503`  | Автоматизации выключены или шифрование секрета вебхука недоступно                |

Ответы с ошибками используют каноническую JSON-форму:

```
{
  "error": "signature verification failed"
}
```

## Связанные страницы[​](#related "Прямая ссылка на Связанные страницы")

* [Справочник REST API](/api-reference/rest.md)
* [Основы работы с API](/developers/api-fundamentals.md)
* [Персональные токены](/accounts/personal-access-tokens.md)
