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.
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.
POST https://intelligence-api.veyra.so/api/routine-triggers/public/{publicId}/fireSet it up
- Open the routine, then Triggers › Add trigger › Webhook.
- Choose a signing mode (below). Start the trigger in test mode (
setupPending: truein the API) while you set up your sender. - Copy the URL and the secret. The secret is shown once; Rotate secret issues a new one and the old one stops working immediately.
- Send a test delivery. In test mode it is checked and recorded but starts no run, so you can confirm authentication safely.
- 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:
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
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, // send exactly the bytes you signed
});
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, # 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,
429or5xx, with the sameIdempotency-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
4xxresponses other than429; 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.