Triggers & workflows

A trigger turns a business event into an Agentic Workforce ME run without an API key in the caller. You create it once, pointed at a published workflow or agent, and receive a secret. From then on, any system that can send an HTTPS POST with an HMAC signature — your monolith, a serverless function, a no-code tool — can start governed agent work. This is how the demo portals start every automated case.

1. The target: a published workflow (or agent)

Point a trigger at an agent when one agent should simply handle the event. Point it at a workflow when you want orchestration: several agents, branches, HTTP calls, waits for external events, human tasks. A workflow is a graph of typed nodes (start, agent, branch, http_request, mcp_tool, wait_event, human_task, parallel, foreach, subworkflow, end…); the trigger payload is available to every node as {{input}}.

{
  "slug": "order-escalation",
  "name": "Order escalation",
  "graph": {
    "nodes": [
      { "id": "start", "type": "start", "config": {} },
      {
        "id": "refunds",
        "type": "agent",
        "config": {
          "agent_id": "…",
          "agent_version_id": "…",           ← the PUBLISHED version id (pinned)
          "input_template": "Handle this order escalation using your tools. Order {{input.order_id}}; reason: {{input.reason}}; idempotency_key: {{input.idempotency_key}}. Full event: {{input}}"
        }
      },
      { "id": "end", "type": "end", "config": {} }
    ],
    "edges": [
      { "from": "start", "to": "refunds" },
      { "from": "refunds", "to": "end" }
    ]
  }
}

• An agent node pins agent_version_id to a published version, so a later draft of the agent cannot change a running workflow until you republish the workflow too.
• input_template is a Mustache-style string; {{input.x}} reads a field, {{input}} injects the whole event as JSON.
• Keep agent nodes free of approval-gated tools: a child run that pauses for an approval fails the workflow (CHILD_RUN_FAILED). Put a gate node before a sensitive step instead, or run the gated agent directly — see Human-in-the-loop approvals.
• The finished workflow run’s output is { outputs: { <node_id>: { text, child_run_id } }, variables }, not a bare { text } — read the node you care about when the run.completed webhook arrives.
• Creating a workflow gives you draft v1; publish it before a trigger can start it (409 WORKFLOW_NOT_PUBLISHED otherwise). Later edits go to the draft (PUT …/versions/draft) and are published as a new version.

# Create returns { "workflow": { "id" } } with draft v1 → publish it
curl -X POST https://console.agenticworkforce.me/v1/workflows/$WORKFLOW_ID/versions/1/publish \
  -H "Authorization: Bearer $HIVE_API_KEY" -H "X-Tenant-Id: $HIVE_TENANT_ID"

# Later changes: PUT the draft, publish the returned version
curl -X PUT https://console.agenticworkforce.me/v1/workflows/$WORKFLOW_ID/versions/draft \
  -H "Authorization: Bearer $HIVE_API_KEY" -H "X-Tenant-Id: $HIVE_TENANT_ID" \
  -H "Content-Type: application/json" -d @graph.json
# → { "version": 2 }

You can also build the graph visually in the console (Workflows → New) and only script the trigger; the API and the console write the same resource.

2. Create the trigger

POST /v1/triggers with kind: "webhook", the target and an optional config. The response includes the public hook path and, once only, the HMAC secret (64 hex characters). Store it with your secrets; if it is lost, POST /v1/triggers/:id/rotate-secret issues a new one and invalidates the old one immediately — there is no overlap window, so deploy the returned value straight away (or create a second trigger, cut over, then delete the old one).

curl -X POST https://console.agenticworkforce.me/v1/triggers \
  -H "Authorization: Bearer $HIVE_API_KEY" -H "X-Tenant-Id: $HIVE_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order escalated",
    "kind": "webhook",
    "target_kind": "workflow",
    "target_id": "'$WORKFLOW_ID'",
    "config": {}
  }'

{
  "id": "019a1b2c-…",
  "name": "Order escalated",
  "kind": "webhook",
  "target_kind": "workflow",
  "target_id": "…",
  "enabled": true,
  "webhook_path": "/hooks/019a1b2c-…",
  "has_secret": true,
  "secret": "3f9c…64 hex chars…"          ← shown once; store it with your secrets
}

Payload → run input

By default the parsed JSON body is the run input. For an agent target the agent reads its prompt from text (or a bare string / input); for a workflow target, nodes address fields as {{input.field}}. If the sending system’s field names are fixed, add config.input_mapping to rename top-level fields on the way in:

{
  "name": "Ticket created",
  "kind": "webhook",
  "target_kind": "agent",
  "target_id": "…",
  "config": {
    "input_mapping": {
      "text": "description",          ← run input field ← TOP-LEVEL body field
      "customer_id": "requester_id"      (no dot paths; unknown fields map to undefined)
    }
  }
}

3. Fire it with a signed request

The hook endpoint is POST /hooks/:triggerId on the API origin. It takes no Authorization or X-Tenant-Id header — the trigger id identifies the tenant and the signature proves the caller holds the secret.

BODY='{"event":"order.escalated","order_id":"ord_1001","reason":"Item arrived damaged","idempotency_key":"escalation:ord_1001:1"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$HIVE_TRIGGER_SECRET" | sed 's/^.* //')

curl -X POST https://console.agenticworkforce.me/hooks/$HIVE_TRIGGER_ID \
  -H "Content-Type: application/json" \
  -H "x-hive-signature: sha256=$SIG" \
  --data-binary "$BODY"
# → 202 { "run_id": "…" }

import { createHmac } from 'node:crypto';

/** x-hive-signature value for the exact bytes you send. */
export function signTriggerBody(secret: string, rawBody: string): string {
  return `sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`;
}

export async function fireTrigger(payload: unknown): Promise<{ run_id: string }> {
  const raw = JSON.stringify(payload);            // sign THIS string, send THIS string
  const res = await fetch(`${process.env.HIVE_API_URL}/hooks/${process.env.HIVE_TRIGGER_ID}`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-hive-signature': signTriggerBody(process.env.HIVE_TRIGGER_SECRET!, raw),
    },
    body: raw,
  });
  if (res.status !== 202) throw new Error(`hook ${res.status}: ${await res.text()}`);
  return (await res.json()) as { run_id: string };
}

import hashlib
import hmac
import json
import os
import urllib.request


def sign_trigger_body(secret: str, raw_body: bytes) -> str:
    """Value for the x-hive-signature header: sha256=<hex HMAC-SHA256(secret, raw body)>."""
    digest = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return "sha256=" + digest


def fire_trigger(payload: dict) -> dict:
    raw = json.dumps(payload, separators=(",", ":")).encode("utf-8")  # sign THESE bytes
    req = urllib.request.Request(
        f"{os.environ['HIVE_API_URL']}/hooks/{os.environ['HIVE_TRIGGER_ID']}",
        data=raw,
        method="POST",
        headers={
            "Content-Type": "application/json",
            "x-hive-signature": sign_trigger_body(os.environ["HIVE_TRIGGER_SECRET"], raw),
        },
    )
    with urllib.request.urlopen(req, timeout=30) as res:  # 202 { "run_id": "…" }
        return json.loads(res.read())


if __name__ == "__main__":
    print(fire_trigger({"event": "order.escalated", "order_id": "ord_1001",
                        "reason": "Item arrived damaged", "idempotency_key": "escalation:ord_1001:1"}))

using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

static string SignTriggerBody(string secret, byte[] rawBody)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    return "sha256=" + Convert.ToHexString(hmac.ComputeHash(rawBody)).ToLowerInvariant();
}

var payload = new { @event = "order.escalated", order_id = "ord_1001",
                    reason = "Item arrived damaged", idempotency_key = "escalation:ord_1001:1" };
byte[] raw = JsonSerializer.SerializeToUtf8Bytes(payload);        // sign THESE bytes

var req = new HttpRequestMessage(HttpMethod.Post,
    $"{Environment.GetEnvironmentVariable("HIVE_API_URL")}/hooks/{Environment.GetEnvironmentVariable("HIVE_TRIGGER_ID")}")
{
    Content = new ByteArrayContent(raw)
};
req.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
req.Headers.Add("x-hive-signature", SignTriggerBody(Environment.GetEnvironmentVariable("HIVE_TRIGGER_SECRET")!, raw));
var res = await new HttpClient().SendAsync(req);                   // 202 { "run_id": "…" }

// Java 17+ (HexFormat). Jackson for the body.
import com.fasterxml.jackson.databind.ObjectMapper;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.HexFormat;
import java.util.Map;

static String signTriggerBody(String secret, byte[] rawBody) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    return "sha256=" + HexFormat.of().formatHex(mac.doFinal(rawBody));
}

byte[] raw = new ObjectMapper().writeValueAsBytes(Map.of(
    "event", "order.escalated", "order_id", "ord_1001",
    "reason", "Item arrived damaged", "idempotency_key", "escalation:ord_1001:1"));   // sign THESE bytes

HttpRequest req = HttpRequest.newBuilder(URI.create(
        System.getenv("HIVE_API_URL") + "/hooks/" + System.getenv("HIVE_TRIGGER_ID")))
    .header("Content-Type", "application/json")
    .header("x-hive-signature", signTriggerBody(System.getenv("HIVE_TRIGGER_SECRET"), raw))
    .POST(HttpRequest.BodyPublishers.ofByteArray(raw))
    .build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString()); // 202

The Python sample and the example’s hive-signing.mjs are executed by this portal’s tests against the platform’s own verifier; the .NET and Java samples are checked for the same header, prefix and algorithm.

Sign the bytes you send

• Serialise once, sign that string, send that string. Re-serialising (or letting an HTTP library re-encode the body) changes bytes and breaks the signature.
• The comparison is constant-time on the full sha256=… string, so the prefix and lowercase hex are part of the contract.
• An empty body is accepted and yields an empty input; a non-JSON body is a 400.

Replay protection and idempotency

• Put a unique idempotency_key (your record id plus a version or timestamp) in the payload and make the agent pass it to your mutating MCP tools, which must be idempotent on it.
• Include occurred_at in the payload and let your tools reject stale events, or check the run’s created_at against it.
• Only ever send hooks over HTTPS, rotate the secret when a system that held it is decommissioned, and keep one trigger per source system so a leak has a small blast radius.

4. Test it

Two authenticated shortcuts skip the HMAC while you develop: test-run on the workflow and fire on the trigger. Both take the same input shape the hook would deliver and return 202 { run_id }; follow the run with SSE or polling.

# Run the workflow without HMAC (same input shape the hook would deliver)
curl -X POST https://console.agenticworkforce.me/v1/workflows/$WORKFLOW_ID/test-run \
  -H "Authorization: Bearer $HIVE_API_KEY" -H "X-Tenant-Id: $HIVE_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"input":{"event":"order.escalated","order_id":"ord_1001","reason":"test","idempotency_key":"test-1"}}'

# Or fire the trigger itself through the authenticated API (no signature needed)
curl -X POST https://console.agenticworkforce.me/v1/triggers/$HIVE_TRIGGER_ID/fire \
  -H "Authorization: Bearer $HIVE_API_KEY" -H "X-Tenant-Id: $HIVE_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"input":{"event":"order.escalated","order_id":"ord_1001","reason":"test","idempotency_key":"test-2"}}'

To exercise the real hook from a laptop, run the API locally or point your script at a staging tenant: the hook endpoint is reachable from anywhere, so no tunnel is needed in this direction (you need one for webhooks, where the platform calls you). GET /v1/runs/:id shows origin with the trigger_id, and the audit log records trigger.fire.

Resuming a workflow from your backend

A workflow can park on a wait_event node until your system says so — a payment settled, a document was signed. Deliver the event to the run with POST /v1/workflows/runs/:runId/events; the payload becomes available to the following nodes. You do not have to wait for the run to reach the node: if it is still queued, running, or parked at an earlier gate, the event is buffered (202 { status: 'buffered' }) and consumed the moment the node is entered — so a re-fired run needs no retry loop on your side. Only a finished run refuses it (409 BAD_STATE).

# A run parked on a wait_event node resumes when your system delivers the event
curl -X POST https://console.agenticworkforce.me/v1/workflows/runs/$RUN_ID/events \
  -H "Authorization: Bearer $HIVE_API_KEY" -H "X-Tenant-Id: $HIVE_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"event_name":"payment.settled","payload":{"settlement_id":"stl_88"}}'
# → 202 { "run_id": "…", "event_name": "payment.settled", "status": "delivered" }
#   ("status": "buffered" when the run has not reached the node yet — no retry needed)

Importing a BPMN 2.0 diagram

Teams that already model their processes in Camunda Modeler, bpmn.io, Signavio, Bizagi or Visio can import the BPMN 2.0 XML instead of redrawing it: POST /v1/workflows/import/bpmn (also Workflows → Import BPMN in the console). The importer is deterministic — the same file always yields the same draft — and produces an import report with one row per BPMN element: how it was mapped (mapped, approximated, placeholder, dropped, unsupported), a confidence, and a fix-it hint. Service, script, business-rule and send tasks become agent nodes that need a binding to one of your published agents (the Zeebe job type / Camunda topic is carried as the hint); Camunda HTTP connectors become http_request nodes; user tasks become gate or human_task; receive tasks and message events become wait_event nodes you resume with POST /v1/workflows/runs/:runId/events. Call it with dry_run: true first, bind the listed nodes, then commit — the result is always a new draft workflow, never a published one. Uploads are capped at 2 MiB and a <!DOCTYPE> is refused before parsing.

Trigger endpoints

Workflow endpoints