Triggering Agents with Webhooks

Agent Webhooks provide a powerful mechanism to trigger an agent's execution from external systems. Unlike the direct API which provides an immediate response, webhooks are designed for asynchronous operations. When you call a webhook, DocsGPT enqueues the agent's task for background processing and immediately returns a task_id. You then use this ID to poll for the result.

This workflow is ideal for integrating with services that expect a quick initial response (e.g., form submissions) or for triggering long-running tasks without tying up a client connection.

Each agent has its own unique webhook URL, which can be generated from the agent's edit page in the DocsGPT UI. This URL includes a secure token for authentication.

API Endpoints

• Webhook URL: http://localhost:7091/api/webhooks/agents/{AGENT_WEBHOOK_TOKEN}
• Task Status URL: http://localhost:7091/api/task_status

For more technical details, you can explore the API swagger documentation available for the cloud version or your local instance.

The Webhook Workflow

The process involves two main steps: triggering the task and polling for the result.

Step 1: Trigger the Webhook

Send an HTTP POST request to the agent's unique webhook URL with the required payload. The structure of this payload should match what the agent's prompt and tools are designed to handle.

• Method: POST
• Response: A JSON object with a task_id. {"task_id": "a1b2c3d4-e5f6-..."}

curl -X POST \
  http://localhost:7091/api/webhooks/agents/your_webhook_token \
  -H "Content-Type: application/json" \
  -d '{"question": "Your message to agent"}'

Step 2: Poll for the Result

Once you have the task_id, periodically send a GET request to the /api/task_status endpoint until the task status is SUCCESS or FAILURE.

• status: The current state of the task (PENDING, STARTED, SUCCESS, FAILURE).
• result: The final output from the agent, available when the status is SUCCESS or FAILURE.

# Replace the task_id with the one you received
curl http://localhost:7091/api/task_status?task_id=YOUR_TASK_ID