Routine trigger webhook

Start a routine from your own systems. The address, the five signing modes, headers, payload, responses, retries and replay protection, with signing code in curl, JavaScript and Python.

Veyra Docs TeamUpdated 3 min readVersion 4 · History

A webhook trigger lets any system start a routine: a monitoring alert, a CI pipeline, a form, another product. Each delivery creates one run; the JSON you send is stored on the run and shown to the agent as data.

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

Set it up

  1. Open the routine, then Triggers › Add trigger › Webhook.
  2. Choose a signing mode (below). Start the trigger in test mode (setupPending: true in the API) while you set up your sender.
  3. Copy the URL and the secret. The secret is shown once; Rotate secret issues a new one and the old one stops working immediately.
  4. Send a test delivery. In test mode it is checked and recorded but starts no run, so you can confirm authentication safely.
  5. Turn test mode off. From now on, each accepted delivery starts a run.

Signing modes

Mode Send Choose it when
bearer (default) Authorization: Bearer <secret> Your sender can set a header.
hmac_sha256 X-Veyra-Timestamp and X-Veyra-Signature You want signed, time-limited requests that cannot be replayed.
github_hmac X-Hub-Signature-256: sha256=<hex> The sender signs like GitHub or Sentry (HMAC of the raw body).
app_webhook Bearer, or X-Hub-Signature-256 A connected app delivers events; the payload is passed to the agent.
none Nothing Only people can choose it; the URL alone is the secret. Agents cannot create unauthenticated triggers.

hmac_sha256

Compute the signature over the timestamp, a dot, and the exact bytes of the body:

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

Send X-Veyra-Timestamp: <timestamp> (Unix seconds or milliseconds) and X-Veyra-Signature: sha256=<signature>. A timestamp outside the trigger's replay window (300 seconds unless you set 30 to 86,400) is refused, and the same signed request is accepted only once.

Headers

Header Required Meaning
Content-Type: application/json Yes The body must be a JSON object.
Authorization bearer, app_webhook Bearer <secret>.
X-Veyra-Timestamp hmac_sha256 Unix time of signing.
X-Veyra-Signature hmac_sha256 sha256= and the hex HMAC. Also accepted for github_hmac.
X-Hub-Signature-256 github_hmac sha256= and the hex HMAC of the raw body.
Idempotency-Key Recommended Your id for this event. A repeat returns the first result. X-GitHub-Delivery is used when present.
X-Veyra-Idempotency-Scope No trigger (default): keys are unique per trigger. routine: unique across the routine's triggers.

Body

Any JSON object, up to 10 MB. Two fields have a meaning of their own:

  • variables: an object of values for the routine's variables, for example {"variables": {"ticket": "SUP-812"}}.
  • Everything else is stored on the run as its payload.

Send a signed request

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, // send exactly the bytes you signed
});
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,  # send exactly the bytes you signed
    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())

With bearer, send only Authorization: Bearer $TRIGGER_SECRET and the JSON.

Responses

Status Body Meaning
202 The routine run Accepted. The run's status says what happened (for example a task was created, or the delivery was coalesced into an active run).
202 {"status": "test_received", "test": true} Test mode: authenticated and recorded, no run started.
202 {"status": "ignored"} A connected app sent an event the trigger does not subscribe to.
400 {"error": ...} The body is not a JSON object, or a header has a wrong value.
401 {"error": ...} Missing or wrong secret or signature, or a timestamp outside the window.
404 {"error": ...} No such trigger.
409 {"error": ...} The routine is archived, or the trigger or routine is not active.
415 {"error": ...} Content-Type is not application/json.

Rejected deliveries are recorded on the trigger (last delivery: rejected) and in the activity log, so you can see failed attempts without exposing what was sent.

Retries and duplicates

  • Retry on a network error, a timeout, 429 or 5xx, with the same Idempotency-Key. A repeated key returns the first result instead of a second run.
  • With hmac_sha256, re-sign each retry with a fresh timestamp; the replay receipt is per signature.
  • Do not retry 4xx responses other than 429; fix the request instead.

What the agent sees

The run's task contains the routine's request. The payload you sent is attached as data, marked as coming from outside and not to be followed as instructions. Give the routine clear instructions for how to treat the payload.

See Fire a public routine trigger, Create a routine trigger and Rotate a routine trigger secret in the API reference.

InboundRoutinesWebhooks