API Keys and Webhooks

Workprentice’s supported programmatic surface is the webhook trigger: external systems start assignment runs with an HTTP POST, authenticated by a workspace API key. There is no general REST API reference beyond this page.

The surface is deliberately narrow. Everything about what happens — the instructions, the tools, the deliverable — lives on the assignment; the webhook only says now, and optionally hands over a payload. That keeps the integration contract small enough to fit in one table (below) while still covering the real cases: a ticketing system that wants an agent on every new ticket, a form tool that wants each submission enriched, a CI pipeline that wants a report after each deploy. Any system that can send an HTTP POST can start agent work.

Workspace API keys

Manage keys in Settings → Workspace → API Keys.

• Create a key with just a name. The full key — it starts with wak_ — is shown exactly once: “This is the only time the full key will be shown. Store it securely.” Afterward, the list shows only each key’s prefix.
• Rotate revokes the old key and issues a new one (also shown once).
• Revoke disables a key immediately.

Name keys after their callers (ticketing-webhook, ci-pipeline) so rotation and revocation stay surgical. When the ticketing vendor has an incident, you rotate ticketing-webhook and the CI pipeline never notices; when a system is decommissioned, you revoke its key and nothing else changes. One shared key across callers turns every one of those events into an all-hands re-credentialing.

The key is shown once — plan for that

Create the key with the calling system’s secret store open in the next tab, paste it straight in, and never write it anywhere else. If it slips through the cracks, rotate — a fresh key takes seconds and the old one dies with it.

The webhook contract

Enable Run via webhook on an assignment’s Schedule section and pick a path. The contract:

Method	POST
URL	https://workprentice.ai/api/v1/hooks/<workspace-id>/<path>
Auth	X-API-Key: wak_… header (whichever key you attached)
Body	Optional JSON — delivered to the run as its webhook payload
Dry run	Append ?run_type=dry_run to block external writes
Success	200 with the started session’s id and run type
Errors	401 bad key · 403 paused assignment or agent · 404 unknown path

A webhook with no key attached accepts unauthenticated calls; attach a key unless you have a specific reason not to.

A worked call

Suppose a support assignment listens at the path ticketing/new-ticket. While you are still tuning the instructions, rehearse with a dry run — the agent does the work, but writes to external systems are blocked:

curl -X POST \
  "https://workprentice.ai/api/v1/hooks/<workspace-id>/ticketing/new-ticket?run_type=dry_run" \
  -H "X-API-Key: wak_..." \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": "12345", "subject": "Cannot log in"}'

A successful trigger returns the session that started:

{ "session_id": "…", "run_type": "dry_run" }

Open that session in Workprentice to watch the run. The JSON body is handed to the agent as the webhook payload, so the assignment’s instructions can refer to it directly — “enrich the ticket in the payload” — and each caller can send whatever fields its runs need. When the output looks right, drop the run_type parameter and point the real system at the same URL; every delivery starts a session and returns its id, so the calling system can link straight to the run.

The error codes are designed to give callers clean signals rather than mysteries: a 401 means the key is wrong or revoked, a 403 means the assignment or its agent is paused, and a 404 means the path does not match any webhook-enabled assignment in the workspace.

The webhook guide walks the full setup with example calls, from creating the key to going live.

Patterns that work

• One key per caller — ticketing-webhook, ci-pipeline, forms-intake. Rotation and revocation stay scoped to the one system involved.
• Dry run while iterating — keep ?run_type=dry_run on the URL until the sessions look right, then remove it. Same endpoint, same payloads, no external writes.
• Pause as the off switch — pausing the assignment makes its webhook return 403, so you can take an intake offline during an incident without revoking any keys, and turn it back on just as cheaply.
• Payload-aware instructions — write the assignment’s instructions against the payload’s fields (“look up ticket_id, draft a response to subject”), so the caller controls the input and the assignment controls everything else.