Перейти к основному содержимому
Открыть Markdown

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

Эта справочная страница описывает публичный приемник для автоматизаций с триггером Входящий 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 сырого телаНет
githubX-Hub-Signature-256: sha256=<lowercase hex HMAC-SHA256>X-GitHub-Delivery, иначе SHA-256 сырого телаX-GitHub-Event
gitlabX-Gitlab-Token равен сохраненному секретному токенуПервый непустой webhook-id, Idempotency-Key, иначе SHA-256 сырого телаX-Gitlab-Event, иначе object_kind из JSON
telegramX-Telegram-Bot-Api-Secret-Token совпадает с сохраненным общим секретомОбязательный JSON update_idПервое распознанное поле обновления Telegram
mattermosttoken в теле, закодированном как форма, или в теле 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Автоматизация выключена
404slug неизвестен или нет пригодного состояния верификатора вебхука
413Тело превышает лимит входящего вебхука в инсталляции
422Автоматизация не привязана к песочнице
429Превышено ограничение частоты запросов по IP или по аккаунту
503Автоматизации выключены или шифрование секрета вебхука недоступно

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

{
"error": "signature verification failed"
}