Вебхук запуска рутины

Запускайте рутину из своих систем. Адрес, пять режимов подписи, заголовки, полезная нагрузка, ответы, повторы и защита от повторного воспроизведения — с кодом подписи на curl, JavaScript и Python.

Veyra Docs TeamОбновлено 3 мин чтенияВерсия 3 · История

Триггер-вебхук позволяет любой системе запустить рутину: оповещению мониторинга, CI-пайплайну, форме, другому продукту. Каждая доставка создаёт один запуск; отправленный JSON сохраняется в запуске и показывается агенту как данные.

HTTP
POST https://intelligence-api.veyra.so/api/routine-triggers/public/{publicId}/fire

Настройка

  1. Откройте рутину, затем Triggers › Add trigger › Webhook.
  2. Выберите режим подписи (см. ниже). Пока настраиваете отправителя, держите триггер в тестовом режиме (setupPending: true в API).
  3. Скопируйте URL и секрет. Секрет показывается только один раз; Rotate secret выпускает новый, а старый сразу перестаёт работать.
  4. Отправьте тестовую доставку. В тестовом режиме она проверяется и записывается, но запуск не создаёт, поэтому аутентификацию можно проверить безопасно.
  5. Выключите тестовый режим. С этого момента каждая принятая доставка запускает рутину.

Режимы подписи

Режим Что отправлять Когда выбирать
bearer (по умолчанию) Authorization: Bearer <secret> Отправитель умеет задавать заголовок.
hmac_sha256 X-Veyra-Timestamp и X-Veyra-Signature Нужны подписанные запросы с ограничением по времени, которые нельзя воспроизвести повторно.
github_hmac X-Hub-Signature-256: sha256=<hex> Отправитель подписывает как GitHub или Sentry (HMAC исходного тела).
app_webhook Bearer или X-Hub-Signature-256 События доставляет подключённое приложение; полезная нагрузка передаётся агенту.
none Ничего Выбрать может только человек; секретом служит сам URL. Агенты не могут создавать триггеры без аутентификации.

hmac_sha256

Вычисляйте подпись по метке времени, точке и точным байтам тела:

Text
signature = hex( HMAC-SHA256( secret, timestamp + "." + raw_body ) )

Отправляйте X-Veyra-Timestamp: <timestamp> (Unix-секунды или миллисекунды) и X-Veyra-Signature: sha256=<signature>. Метка времени вне окна защиты триггера (300 секунд, если вы не задали значение от 30 до 86 400) отклоняется, а один и тот же подписанный запрос принимается только один раз.

Заголовки

Заголовок Обязателен Значение
Content-Type: application/json Да Тело должно быть JSON-объектом.
Authorization bearer, app_webhook Bearer <secret>.
X-Veyra-Timestamp hmac_sha256 Unix-время подписи.
X-Veyra-Signature hmac_sha256 sha256= и HMAC в шестнадцатеричном виде. Принимается и для github_hmac.
X-Hub-Signature-256 github_hmac sha256= и шестнадцатеричный HMAC исходного тела.
Idempotency-Key Рекомендуется Ваш идентификатор события. Повтор возвращает первый результат. Если есть X-GitHub-Delivery, используется он.
X-Veyra-Idempotency-Scope Нет trigger (по умолчанию): ключи уникальны в пределах триггера. routine: уникальны для всех триггеров рутины.

Тело запроса

Любой JSON-объект размером до 10 МБ. У двух полей особый смысл:

  • variables: объект со значениями для переменных рутины, например {"variables": {"ticket": "SUP-812"}}.
  • Всё остальное сохраняется в запуске как полезная нагрузка.

Отправка подписанного запроса

curl
URL="https://intelligence-api.veyra.so/api/routine-triggers/public/$PUBLIC_ID/fire"
BODY='{"variables":{"ticket":"SUP-812"},"severity":"high"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$TRIGGER_SECRET" -hex | sed 's/^.* //')

curl -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Veyra-Timestamp: $TS" \
  -H "X-Veyra-Signature: sha256=$SIG" \
  -H "Idempotency-Key: SUP-812" \
  --data-binary "$BODY"
JavaScript
import { createHmac } from "node:crypto";

const body = JSON.stringify({ variables: { ticket: "SUP-812" }, severity: "high" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", process.env.VEYRA_TRIGGER_SECRET)
  .update(`${timestamp}.`)
  .update(body)
  .digest("hex");

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Veyra-Timestamp": timestamp,
    "X-Veyra-Signature": `sha256=${signature}`,
    "Idempotency-Key": "SUP-812",
  },
  body, // отправляйте ровно те байты, которые подписали
});
console.log(response.status, await response.json());
Python
import hashlib, hmac, json, os, time
import requests

secret = os.environ["VEYRA_TRIGGER_SECRET"].encode()
body = json.dumps({"variables": {"ticket": "SUP-812"}, "severity": "high"}, separators=(",", ":")).encode()
timestamp = str(int(time.time()))
signature = hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()

response = requests.post(
    url,
    data=body,  # отправляйте ровно те байты, которые подписали
    headers={
        "Content-Type": "application/json",
        "X-Veyra-Timestamp": timestamp,
        "X-Veyra-Signature": f"sha256={signature}",
        "Idempotency-Key": "SUP-812",
    },
    timeout=15,
)
print(response.status_code, response.json())

В режиме bearer отправляйте только Authorization: Bearer $TRIGGER_SECRET и JSON.

Ответы

Код Тело Значение
202 Запуск рутины Принято. Поле status запуска говорит, что произошло (например, создана задача или доставка объединена с активным запуском).
202 {"status": "test_received", "test": true} Тестовый режим: аутентифицировано и записано, запуск не создан.
202 {"status": "ignored"} Подключённое приложение прислало событие, на которое триггер не подписан.
400 {"error": ...} Тело не является JSON-объектом или в заголовке неверное значение.
401 {"error": ...} Нет секрета или подписи, они неверны, либо метка времени вне окна.
404 {"error": ...} Такого триггера нет.
409 {"error": ...} Рутина в архиве, либо триггер или рутина неактивны.
415 {"error": ...} Content-Type — не application/json.

Отклонённые доставки записываются в триггере (last delivery: rejected) и в журнале активности, так что неудачные попытки видны без раскрытия отправленных данных.

Повторы и дубликаты

  • При сетевой ошибке, тайм-ауте, 429 или 5xx повторяйте запрос с тем же Idempotency-Key. Повторный ключ возвращает первый результат вместо второго запуска.
  • В режиме hmac_sha256 подписывайте каждый повтор заново со свежей меткой времени: защита от повторов действует для каждой подписи.
  • Не повторяйте ответы 4xx, кроме 429; исправьте запрос.

Что видит агент

Задача запуска содержит запрос рутины. Отправленная полезная нагрузка прикладывается как данные с пометкой, что она пришла извне и не должна выполняться как инструкции. Дайте рутине чёткие указания, как обращаться с полезной нагрузкой.

См. в справочнике API: Fire a public routine trigger, Create a routine trigger и Rotate a routine trigger secret.

ВебхукиВходящиеРутины