API Keys and Webhooks

One credential opens every programmatic surface: the workspace API key. This page covers the webhook trigger, where external systems start assignment runs with an HTTP POST. The same key also connects an MCP client to your workspace and lets other agent frameworks delegate work over A2A. There is no general REST API reference beyond these.

The webhook 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), or sender-signature mode below
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 or missing credential · 403 paused assignment or agent · 404 unknown path

A credential is required in either mode. Every delivery starts a real agent run, so a webhook with no credential bound is not an open endpoint — it rejects every call with a 401 until you attach an API key (the default mode) or a signing secret (sender-signature mode, below).

Sender-signature authentication

Some SaaS senders cannot set custom headers on their webhook deliveries, so they cannot present an API key. Intercom is the canonical example: it signs each delivery instead, sending an X-Hub-Signature header carrying an HMAC-SHA1 of the raw request body computed with your Intercom app’s client secret.

For those senders, switch the webhook’s Authentication to Sender signature and paste the signing secret (for Intercom, the app’s client secret from its Basic Info page). Deliveries then authenticate by signature: a missing or wrong X-Hub-Signature is a 401, exactly like a bad API key. The secret is write-only — it is never shown again after saving — and can be rotated by pasting a new value. Everything else in the contract, including ?run_type=dry_run, works the same in both modes.

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 missing, wrong, revoked, or never attached to the assignment in the first place, 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.