Skip to content

Webhooks

A webhook starts a workflow run when another system sends an HTTP POST request with a Webhook API key. A webhook is one kind of trigger. The other kind is a schedule.

You need a saved workflow and a workspace with at least one agent.

Create a Webhook API Key

  1. Follow Create a key. Set Type to Webhook. Under Accessible Workflows, select Select workflows and pick the workflows this key may start.
  2. In the dialog Copy your API key, select Copy and store the secret. AgentZ shows it once.

A Webhook key starts with whk_. See API keys to list and revoke keys.

Warning

Anyone with the key can start runs of the selected workflows. Store it like a password and set an expiry.

Send the Request

Send a POST request to the webhook path on your AgentZ host. The path holds the agent name from the Agents page and the name of the saved workflow.

For example, the agent my-first-agent and the workflow ticket-triage give this path. The example workflow declares one string input named ticket_id.

/api/workflow/my-first-agent/ticket-triage/webhook

Put the key in the X-API-Key header. The body is JSON, and AgentZ reads it as JSON whatever the Content-Type is. The body must match the inputs of the workflow. The optional query parameter timeout_seconds sets the run timeout. The default is 3,600 and the maximum is 604,800.

curl -X POST "https://agentzharness.ai/api/workflow/my-first-agent/ticket-triage/webhook" \
  -H "X-API-Key: $WEBHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": "T-1042"}'

The shell variable WEBHOOK_KEY holds the key you copied. On a self-hosted install, replace https://agentzharness.ai with your own host. A reply with the status 202 means the run started.

Read the Response

Status Meaning
202 AgentZ accepted the request and created a run.
400 The body is not valid JSON, the body does not match the workflow input contract, or timeout_seconds is outside 1 to 604,800.
401 The key is missing, invalid or not allowed to start this workflow.
404 The workflow does not exist.

A 202 response holds a run summary with fields such as name, workflow_name, trigger_type, status and timeout_seconds. The trigger_type is Webhook.

Find Webhook Runs in the Web App

  1. Select Triggers in the workspace sidebar.
  2. Pick the agent in Agent, then set Type to Webhook.
  3. Read the table with the columns API key, Workflow and Last triggered.

A row appears after the key starts its first run. The table shows "No webhooks found." until then.

Next Step

Continue with Dashboards.