Rig Getting started Docs Images GitLab Hub

Triggers

Webhook HTTP on the runtime. Nix fields for triggerProvider and trigger are in Docs. Raw: /raw/triggers.md.

POST /v1/agents/:agent/:route

Not behind the API bearer token. The provider secret is the credential. :agent is the pulled image name or name:tag. :route is a provider routes[].path, which may include :trigger.

POST /v1/agents/agency-tester/webhooks/hooks/hello

The body is the vendor payload. JSON is parsed when Content-Type is empty or includes json. HMAC already ran on the raw body.

Query

Session and workdir ride on the query string so HMAC of the body stays valid.

NameMeaning
session Session name to reuse or create. A pinned stopped or failed session stays 409. An unpinned dead name may take a live NATO sibling of the image name.
workdir Persistent workdir name under $RIG_DATA_DIR/workdirs/.
workdirHost Host bind path. The path must exist.
workdirClone Git URL. Same scheme rules as --workdir-clone.
workdirRef Clone ref. Used with workdirClone. 
POST /v1/agents/agency-tester/webhooks/hooks/hello?session=notes&workdirHost=/home/me/proj

Status

CodeMeaning
200 A matched kind has respond. Body is the rendered template. Content-Type is respond.contentType, or application/json if that field is unset in the HTTP writer.
202 Accepted. JSON { ok: true }, plus session when a session was resolved. Also returned when the provider declares no kinds.
204 No kind matched, or the request is a duplicate dedup key.
401 Token or HMAC failed. JSON { error: "unauthorized" }.
404 Agent home missing, no trigger routes, or no matching route. Errors are agent not found, no trigger routes for agent, or no matching route.
409 Prompt target session is stopped or failed. JSON { error: "session is not running" }.
503 The provider auth.env key is missing. JSON { error: "missing secret: <key>" }.

A handler that exits non-zero is logged and does not change a 202.

Dispatch order

  1. Resolve the agent home.
  2. Match a provider route.
  3. Read the provider secret. Missing is 503.
  4. Verify token or HMAC. Fail is 401.
  5. Parse JSON when the content type allows it.
  6. Match kinds. None is 204. No kinds declared is 202.
  7. Render a respond kind and return 200.
  8. Drop duplicates. Duplicate is 204.
  9. Resolve the prompt session when any matching trigger has prompt or session.
  10. Run matching handlers as bun children, 10 second cap, stdin JSON { headers, query, payload, body }.
  11. Queue rendered prompts on that session, one at a time, in order. Return 202 once queued, or 409.

The image must already be on that runtime. Rig does not pull on a webhook.

Invariants