Automation

Trigger a workflow with a webhook

Create a webhook trigger, send request data to a skill, verify the resulting execution, and remove the trigger.

Create a public webhook endpoint for a skill, invoke it with synthetic request data, and remove it when the integration is no longer needed. Agent Studio accepts GET and POST webhook calls and passes the request body, headers, and query parameters into the execution input.

Before you begin

You need a skill ID, an authenticated Clerk session for trigger administration, and an HTTP client such as curl. The skill must be ready to execute with the input you send. Set these local shell variables without committing their values:

bash

export AGENT_STUDIO_URL="https://agent-studio.example.com"
export SKILL_ID="<skill-id>"
export CLERK_SESSION_TOKEN="<session-token>"

The administrative /api/triggers route requires the signed-in session. The generated /api/triggers/webhook/:token route is the endpoint called by the external system; treat its token as a credential.

Request flow

The authenticated creator receives a webhook token. An external system then uses that token to submit a request, which Agent Studio maps into an execution payload.

Create and invoke the webhook

Create the trigger

Send POST /api/triggers with type set to webhook, the target skillId, and a descriptive name. This example uses a support-ticket workflow and relies on the generated token as the endpoint credential.

bash

curl --fail-with-body \
  --request POST "$AGENT_STUDIO_URL/api/triggers" \
  --header "Content-Type: application/json" \
  --header "Cookie: __session=$CLERK_SESSION_TOKEN" \
  --data "{
    \"type\": \"webhook\",
    \"skillId\": \"$SKILL_ID\",
    \"name\": \"Support ticket intake\"
  }"

The response has success: true and returns the webhook under data. Save its id for administration and its generated token for invocation. Do not put the token in logs or source control.

Map the incoming request

Design the caller's request around the envelope Agent Studio supplies to the skill:

Input member	Source
`body`	Parsed JSON request body. A non-JSON body becomes `{ "raw": "..." }`; an empty body becomes an empty object.
`headers`	Request headers with lowercase names.
`query`	URL query parameters as string values.

For example, a support-ticket skill can read the ticket from body.ticket, the requested queue from query.queue, and a source identifier from the x-source header. Keep essential input in the body or query rather than depending on transport headers added by intermediaries.

Invoke the endpoint

Replace <webhook-token> with the returned token and send synthetic data:

bash

curl --fail-with-body \
  --request POST "$AGENT_STUDIO_URL/api/triggers/webhook/<webhook-token>?queue=documentation" \
  --header "Content-Type: application/json" \
  --header "X-Source: support-portal" \
  --data '{
    "ticket": {
      "id": "TKT-1042",
      "summary": "Clarify the installation prerequisites",
      "priority": "normal"
    }
  }'

Agent Studio parses the JSON, starts the configured skill, and returns success: true with the execution result under data. For a query-only integration, send a GET request to the same token route; it follows the same execution path.

Verify the execution

Open the execution returned by the webhook response in Agent Studio, or find the new run in the execution list. Confirm that the input contains the expected body, lowercase headers, and query values, then inspect the steps and final status.

The request is verified only when the execution belongs to the intended skill and its input contains the synthetic ticket values—not merely when the webhook returns an HTTP success response. See Inspect an execution trace for the full inspection workflow.

Delete the trigger

When the integration is no longer needed, delete it with the saved trigger ID:

bash

curl --fail-with-body \
  --request DELETE "$AGENT_STUDIO_URL/api/triggers?type=webhook&id=<trigger-id>" \
  --header "Cookie: __session=$CLERK_SESSION_TOKEN"

The response contains success: true and the message Trigger deleted. A subsequent invocation with the old token no longer finds the trigger.

✅A successful test produces a new execution for the target skill, preserves the example ticket in the execution input, and returns its result to the caller.

Troubleshooting

Next, run and find executions to monitor webhook-initiated runs, or schedule a workflow with cron for time-based automation.