Backend integration
Overview & reference architecture
The closed loop the demo portals implement: signed triggers, MCP tools, signed webhooks and human approvals — who owns what, the security model and a build checklist.
Connecting a backend to Agentic Workforce ME is one closed loop, and the demo portals (Meridian, Dubai Police) all implement the same one: a business event in your system becomes a signed request to the platform; a published workflow or agent runs; the agent reads and writes your data through an MCP server your backend exposes; privileged steps pause for a human; signed webhooks tell your backend what happened. Everything is created by a script so every environment looks the same.
The loop, end to end
A business event happens in your system
An invoice is filed, a complaint is submitted, an order is escalated. Your backend signs the JSON body with the trigger secret and fires the hook. Details
POST /hooks/:triggerId · x-hive-signature: sha256=…The platform verifies the HMAC and starts a run
The trigger identifies the tenant and target; the raw body (optionally remapped) becomes the run input of a published workflow or agent. You get 202 { run_id }. Details
The agent works through your MCP server
Reads and writes go to tools your backend exposes over Streamable HTTP. The gateway injects the encrypted connection credential per call; every call is a redacted run step. Details
POST https://your-api/mcp · Authorization: Bearer <connection>Privileged tools pause for a human
An approval policy on orders.refund interrupts the run; the platform emits approval.requested. Your UI (or the console) decides through the approvals API with a server-held key. Details
Signed webhooks close the loop
run.completed / run.failed carry the output, cost and the run id you stored; verify Hive-Signature, de-duplicate on the event id, acknowledge fast, apply asynchronously. Details
Everything is provisioned as code
A setup script creates the MCP server, connection, grants, policies, workflow, trigger and webhook idempotently, keeping the once-shown secrets in your secret store. Details
setup-hive · POST /v1/* (admin key)Steps 1–2 and 5 are HTTP calls between your servers and the platform; step 3 is the platform calling you; step 4 is a person, in the console or in your UI. Each number links to the page that documents that piece.
Who owns what
| Area | The platform owns | Your backend owns |
|---|---|---|
| Identity of callers | API keys (hashed), roles, tenant isolation with row-level security, audit of every privileged mutation. | Keep API keys and secrets server-side; one key per service; rotate by create-switch-revoke. |
| Inbound events | Verifies x-hive-signature, maps the body to run input, enqueues the run, records the trigger as the run origin. | Sign the raw body with the trigger secret; carry your own record id and an idempotency key in the payload. |
| Agent behaviour | Runs the published manifest: persona, model, tools ∩ grants, guardrails, budgets, HITL rules. | Author and publish the agent/workflow; grant only the tools it needs. |
| Acting on your systems | Calls your MCP tools through the Tool Gateway; decrypts the connection credential per call; validates args against your JSON Schema; redacts inputs/outputs in run steps. | Host the MCP server; check the bearer token in constant time; make mutations idempotent; return clear errors. |
| Human approval | Interrupts the run on matching policies, expires by SLA, escalates, records who decided. | Surface pending approvals in your UI and decide through the API with a server-held key, or use the console. |
| Outbound notifications | Signs and delivers webhooks with retries and a ledger you can read. | Verify, de-duplicate on the event id, ACK 2xx quickly, apply asynchronously, tolerate out-of-order delivery. |
Security model in one screen
Identity of your servers
- A tenant API key (
Authorization: Bearer hive_…+X-Tenant-Id) identifies your service. Keys are hashed at rest, shown once, act with theadminrole and appear asapikey:<id>in the audit log. One key per service; rotate by create → switch → revoke. API keys & authentication
HMAC in both directions
- You → platform (triggers):
x-hive-signature:sha256=<hex>, HMAC-SHA256 of the trigger secret over the raw request body bytes, exactly as sent. There is no timestamp in the signed material, so put your own idempotency key in the payload and make your MCP mutations idempotent. Triggers - Platform → you (webhooks):
Hive-Signature:t=<unix seconds>,v1=<hex HMAC-SHA256>, HMAC-SHA256 of the endpoint secret over"<t>.<raw body>"; reject anything older than 300 s and de-duplicate on the event id. Webhooks
Credentials never reach a model
- The bearer token your MCP server expects is stored platform-side as a connection: AES-256-GCM encrypted at rest, decrypted only inside the Tool Gateway for the duration of a call, never returned by the API, never serialised into prompts, run state or checkpoints. MCP
- Tool grants are default-deny; the agent manifest can only narrow them further. Approval policies interrupt the run itself (a checkpointed
interrupt()), so nothing runs while a request is pending. They pause direct agent runs; inside a workflow, gate a step with agatenode instead. Approvals
Everything is audited
Runs and their steps (runs, run_steps with redacted inputs/outputs), model and tool consumption (usage_events), and every privileged mutation, approval decision and credential access (audit_log, append-only). A run started by a trigger records the trigger as its origin; one started by your key records the key.
Build checklist
- Create a dedicated API key for the integration and store it with your other secrets.
- Publish the agent (and workflow, if you orchestrate) that will handle the event.
- Expose an MCP server with the two or three tools the agent needs; protect it with a bearer token.
- Register the MCP server, store the token as a connection, grant the tools to the agent.
- Put an approval policy on every tool that moves money or changes state irreversibly — and run that agent directly (
POST /v1/agents/:id/runs), not as a workflow agent node; inside workflows gate steps with agatenode. - Create a webhook trigger on the workflow/agent; save the once-shown secret; sign requests over the raw body.
- Subscribe a webhook endpoint to
run.completed,run.failed,approval.requested; verifyHive-Signature; de-duplicate onid. - Store the returned
run_idon your record so the completion webhook can find it. - Decide approvals from your UI via a server-side proxy (never ship the key to the browser) or from the console.
- Put all of the above in an idempotent
setup-hivescript and run it in every environment.
A runnable reference
examples/backend-integration-node is a small Express service that does all of the above in about 400 lines: a signed-trigger endpoint, an MCP server with orders.get and orders.refund, a webhook receiver that verifies and de-duplicates, an approvals proxy, and a setup-hive script that provisions the platform side idempotently. The portal’s drift tests execute its signing and verification helpers against the platform’s own signer and verifier.