Calling agents over HTTP
A published webhook or form agent has a public trigger URL. POST a JSON body and it becomes the run's inputs. The one decision that matters to the caller is how the response comes back — and it is controlled by two query parameters.
The trigger URL
POST https://<your-sarb-host>/v1/webhooks/<tenant>/<agent-slug>- Only a published version answers — before the first publish the URL returns 409 not_published.
- A JSON body becomes the run inputs verbatim; contract fields describe what the agent expects.
- multipart/form-data is accepted for file inputs: each file part arrives as {filename, content_type, data_b64}.
Three response modes
| Mode | Query | The caller receives |
|---|---|---|
| Async (default) | — | 202 + {run_id, status} immediately; the run continues in the background. |
| Wait | ?wait=60 | Blocks up to that many seconds and returns the full run result envelope (status, output, error). |
| Raw | ?wait=60&raw=1 | Blocks and the response body is exactly the respond step's output — a drop-in for n8n's Respond to Webhook. A failed run or an elapsed wait becomes an HTTP error status. |
The wait ceiling is 60 seconds by default; a deployment can raise it with SARB_MAX_WAIT_SECONDS. If the wait elapses in the default mode, the caller falls back to the async 202 handle.
curl -X POST 'https://<host>/v1/webhooks/default/my-agent?wait=60&raw=1' \
-H 'Content-Type: application/json' \
-d '{"goal": "Increase NPS by 10% by Q4"}'Securing the webhook
By default a published webhook is open — anyone with the URL can start runs. Set Inbound auth on the bar above the canvas; the secret lives in an encrypted credential, never in the spec, and the Webhook panel's example call automatically includes whatever auth you set.
| Mode | The caller sends | The credential holds |
|---|---|---|
| Header token | The named header (e.g. X-Webhook-Token) with the token value. | {token} — a generic Bearer token credential works. |
| Basic auth | An HTTP Basic Authorization header. | {username, password}. |
| HMAC-SHA256 | The hex HMAC of the raw body in the signature header (Stripe/GitHub style). | {secret} — the signing key. |
Fetching results later (async mode)
The async 202 body carries a run_id. The runs API returns the full result — it is a management endpoint, so the request needs an API token (or a session): create one and send it as a bearer token.
curl -H 'Authorization: Bearer <api-token>' \
https://<host>/v1/runs/<run_id>Testing without a real caller
- Test draft — run the saved draft with sample inputs from the editor, before anything is published.
- Listen — capture one real inbound payload as a test sample without starting a run, to design against the true shape.
- Webhook panel — the editor builds a ready-to-paste URL and curl example for each response mode.