Skip to main content

Schedules and webhooks

A trigger starts an agent run that nobody pressed Run for:

  • a schedule runs the agent at set times, such as every weekday at 09:00 in Dubai
  • a webhook runs it when another system posts to a signed URL

Each run uses the agent's live version at that moment, with the trigger's input and run variables. It is an ordinary run: it is listed with the agent's runs in Runs & traces, and a write tool still stops at its approval gate for a person. The trigger doesn't wait for the answer.

Add a trigger​

You need the developer or admin role on the project. Viewers can see triggers and their history.

  1. Open the workflow in Workflows and choose Triggers.
  2. Choose Add schedule or Add webhook, and give it a Name.
  3. Set the Input, the message the agent is given, and any Run variables, one name=value per line, for the workflow's vars.<name> conditions. See Run variables.
  4. For a schedule, set when it runs (below).
  5. Choose Create trigger.

The panel lists each trigger with whether it is on, when it fires next, when it last fired and how many times, and its History of firings with a link to each run. Run now fires it at once. Edit, switch off and Delete are audited.

Schedules​

Pick a Repeat preset (every hour, every day at 09:00, weekdays at 09:00, Mondays at 09:00, the 1st of the month at 09:00) or Custom, and enter a five-field Cron: minute, hour, day of month, month, day of week, such as 0 9 * * mon-fri.

The schedule runs in the Time zone you give, an IANA name such as Asia/Dubai, and follows daylight saving. A schedule fires at most every 5 minutes by default.

If the platform was down when a schedule was due, the missed firing runs once when it comes back, not once per missed slot.

Webhooks​

Creating a webhook shows its signing secret once. Copy it then; it isn't shown again. Lost it? Choose New secret. The secret is kept in Vault, never in the database.

Another system starts a run by posting to the trigger's URL:

BODY='{"input": "Summarise the open tickets", "variables": {"team": "billing"}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$TRIGGER_SECRET" -hex | sed 's/^.* //')

curl -X POST "$ORCHESTRATE_API/hooks/workflow-triggers/$TRIGGER_ID" \
-H "X-Orchestrate-Signature: t=$T,v1=$SIG" \
-H "Content-Type: application/json" \
-d "$BODY"
  • Signature. X-Orchestrate-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of <t>.<raw body> with the signing secret. This is the same scheme the Agent API signs its own webhooks with, so one receiver library serves both ways.
  • Freshness. t must be within 5 minutes of the platform's clock, and each signature is accepted once, so a captured delivery can't be replayed.
  • Body, up to 64 KiB. JSON with input (and optionally variables) sets the run's input. Any other body is the input as it is. An empty body uses the trigger's own input.
  • Answer. 202 when the run started. 409 when the delivery was received but no run could start, for example because the agent has no live version; the firing says why. An unknown or switched-off trigger, or a bad signature, is refused without saying which.

API​

The console uses GET, POST, PATCH and DELETE /workflow-triggers, with /workflow-triggers/{id}/fire, /rotate-secret and /fires. See the Agents API.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →