Вебхук запуска рутины
Запускайте рутину из своих систем. Адрес, пять режимов подписи, заголовки, полезная нагрузка, ответы, повторы и защита от повторного воспроизведения — с кодом подписи на curl, JavaScript и Python.
Триггер-вебхук позволяет любой системе запустить рутину: оповещению мониторинга, CI-пайплайну, форме, другому продукту. Каждая доставка создаёт один запуск; отправленный JSON сохраняется в запуске и показывается агенту как данные.
POST https://intelligence-api.veyra.so/api/routine-triggers/public/{publicId}/fireНастройка
- Откройте рутину, затем Triggers › Add trigger › Webhook.
- Выберите режим подписи (см. ниже). Пока настраиваете отправителя, держите триггер в тестовом режиме (
setupPending: trueв API). - Скопируйте URL и секрет. Секрет показывается только один раз; Rotate secret выпускает новый, а старый сразу перестаёт работать.
- Отправьте тестовую доставку. В тестовом режиме она проверяется и записывается, но запуск не создаёт, поэтому аутентификацию можно проверить безопасно.
- Выключите тестовый режим. С этого момента каждая принятая доставка запускает рутину.
Режимы подписи
| Режим | Что отправлять | Когда выбирать |
|---|---|---|
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
Вычисляйте подпись по метке времени, точке и точным байтам тела:
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"}}.- Всё остальное сохраняется в запуске как полезная нагрузка.
Отправка подписанного запроса
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"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());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.