Trigger an Assignment from a Webhook

Webhooks let other systems start agent work the moment something happens — a new ticket, a form submission, a deploy. Any system that can send an HTTP POST can trigger an assignment, and every call must carry a credential: a webhook with none attached refuses every delivery.

Create an API key. Open Workspace settings → API keys and choose New API key (Create your first API key when the list is empty). Creating keys takes a workspace admin. Name the key after the caller (for example, ticketing-webhook) and choose Create API key. The full key — it starts with wak_ — is shown exactly once; store it in the calling system’s secret store. Afterward the list shows only the key’s prefix, and you can rotate or revoke it anytime.
Enable the webhook trigger. Open the assignment and go to its Schedule tab. Check Run via webhook, leave Authentication on API key (X-API-Key header), and pick your key in the API key dropdown; when the workspace has exactly one active key, it is attached for you. Then enter a Webhook path (for example, ticketing/new-ticket). Once the path is set, the full URL appears with a copy button:
```
https://workprentice.ai/api/v1/hooks/<workspace-id>/ticketing/new-ticket
```
The trigger is not saved until it has both a path and an active key, and the tab shows a warning until it does.
Send a test delivery. POST a sample payload with the key in the X-API-Key header:
Terminal window
```
curl -X POST \
  "https://workprentice.ai/api/v1/hooks/<workspace-id>/ticketing/new-ticket" \
  -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": "…", "status": "started", "run_type": "live" }
```
Open that session in Workprentice to watch the run. The JSON body you POST reaches the agent as the webhook payload, so the assignment’s instructions can refer to it (“enrich the ticket in the payload…”).

A test delivery is a real run. The agent’s own tool calls — updating a ticket, posting to Slack — happen for real, so point early tests at sample records. A dry run holds back only the follow-up actions on the assignment’s Hooks tab.
Go live. Point the real system at the URL. Every delivery starts a session and returns its id. When a call is refused, the status code says why; the codes are listed in the webhook contract.

Instructions for a webhook-triggered assignment read like any other, except they can lean on the payload. For the ticketing example:

A new support ticket arrives as the webhook payload, with a ticket id and subject. Look up the ticket in Zendesk and classify its severity. Draft a suggested first response, and add a row to the Ticket Triage data table with the ticket id, severity, and your draft. If the ticket describes an outage, escalate to my Inbox as Urgent instead of waiting for the next review.

Senders that sign instead of sending a key

Some services cannot add a custom header to their webhooks, so they cannot present an API key. Intercom is the usual example: it signs each delivery with a shared secret and sends the result in an X-Hub-Signature header. For those senders, set Authentication to Sender signature in step 2 and paste the sender’s secret into Signing secret (for Intercom, the app’s client secret) instead of picking a key. Sender-signature authentication covers how deliveries are verified.

Variations

Anything that can send an HTTP POST works as a caller:

Form submission to enriched lead. Have your form tool POST each new signup. The agent enriches the lead with ZoomInfo or Clay, then writes the result into HubSpot or Salesforce — enrichment done before anyone opens the CRM.
Post-deploy check. A key named ci-pipeline and a POST at the end of each deploy: the agent checks Sentry for new errors against the release and escalates to your Inbox only when something regressed, so a quiet deploy stays quiet.
Triage queue. Each delivery appends a row to a data table with a status column a human advances — the webhook fills the queue, and the table is the queue.

Key management, headers, and error codes are in API keys and webhooks.