Входящие вебхуки
Эта справочная страница описывает публичный приемник для автоматизаций с триггером Входящий webhook:
POST {webhook_url}
Создайте или прочитайте автоматизацию через REST API и
используйте полученный webhook_url. URL содержит публичный идентификатор
slug автоматизации; не конструируйте его из ID автоматизации.
Аутентификация
Приемник не принимает 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
Используйте 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.
Параметры универсального 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
Следующий запрос сохраняет те же байты, по которым вычислена подпись:
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 вебхука и секрет в системе контроля версий или истории оболочки.
Подтверждение и дедупликация
Корректный запрос проверяется и надежно ставится в очередь до ответа приемника. Приемник не ждет пробуждения целевой песочницы или завершения действия.
Новая доставка:
{
"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 доставки провайдера, если
одинаковые тела запросов могут быть разными легитимными событиями.
Что получает действие
При постановке запуска в очередь приемник фиксирует проверенное тело, выбранные заголовки, целевую песочницу и конфигурацию действия. Последующие изменения не перенаправят уже поставленную в очередь доставку.
Для действия 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_*, включая
триггер, запуск, автоматизацию, тип события и ключ дедупликации, когда они
доступны.
Порядок и повторы
Режим concurrency_mode управляет выполнением:
parallelдопускает независимые запуски;serialупорядочивает все запуски одной автоматизации;partitionedпока доступен только для Telegram и независимо упорядочивает каждую определенную переписку.
Действие HTTP POST считается успешным при ответе 2xx. Ответы не 2xx и
сбои соединения следуют политике повторных попыток запуска. Завершенная команда
считается успешной даже при ненулевом коде выхода, если для действия не задано
retry_on_nonzero: true; сбои инфраструктуры повторяются.
max_attempts находится в диапазоне 1..20; инсталляция по умолчанию задает
для автоматизаций с триггером Входящий webhook значение 5. Экспоненциальная задержка и
конкурентность обработчика запусков автоматизаций — настройки инсталляции,
поэтому клиентам нельзя зависеть от точного времени повтора.
Лимиты и хранение
- Лимит входящего тела по умолчанию равен 1 МиБ. Инсталляция может изменить его;
слишком большой запрос получает
413. - До проверки подписи действует ограничение частоты запросов по IP, а после
определения
slug— по аккаунту. - Сырые тела вебхуков и выбранные заголовки хранятся согласно
payload_retention_hours(1..720, по умолчанию24), после чего удаляются из истории запусков. После удаления тело запроса нельзя отправить повторно вручную. - Ответ
202подтверждает постановку в очередь или повторную доставку, но не успех действия. Проверяйте запуск автоматизации через аутентифицированный REST API.
Ответы
| Статус | Значение |
|---|---|
202 | Событие принято или подтверждено как повторная доставка |
400 | Тело запроса провайдера некорректно, например в JSON от Telegram нет update_id |
401 | Подпись или общий токен отсутствует либо неверен |
403 | Автоматизация выключена |
404 | slug неизвестен или нет пригодного состояния верификатора вебхука |
413 | Тело превышает лимит входящего вебхука в инсталляции |
422 | Автоматизация не привязана к песочнице |
429 | Превышено ограничение частоты запросов по IP или по аккаунту |
503 | Автоматизации выключены или шифрование секрета вебхука недоступно |
Ответы с ошибками используют каноническую JSON-форму:
{
"error": "signature verification failed"
}