import { Callout, Tabs } from 'nextra/components';

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-..."}

<Tabs items={['cURL', 'Python', 'JavaScript']}> <Tabs.Tab> bash curl -X POST \ http://localhost:7091/api/webhooks/agents/your_webhook_token \ -H "Content-Type: application/json" \ -d '{"question": "Your message to agent"}' </Tabs.Tab> <Tabs.Tab> ```python import requests

WEBHOOK_URL = "http://localhost:7091/api/webhooks/agents/your_webhook_token"
payload = {"question": "Your message to agent"}

try:
    response = requests.post(WEBHOOK_URL, json=payload)
    response.raise_for_status()
    task_id = response.json().get("task_id")
    print(f"Task successfully created with ID: {task_id}")
except requests.exceptions.RequestException as e:
    print(f"Error triggering webhook: {e}")
```

</Tabs.Tab> <Tabs.Tab> ```javascript const webhookUrl = 'http://localhost:7091/api/webhooks/agents/your_webhook_token'; const payload = { question: 'Your message to agent' };

async function triggerWebhook() {
  try {
    const response = await fetch(webhookUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });
    if (!response.ok) throw new Error(`HTTP error! ${response.status}`);
    const data = await response.json();
    console.log(`Task successfully created with ID: ${data.task_id}`);
    return data.task_id;
  } catch (error) {
    console.error('Error triggering webhook:', error);
  }
}

triggerWebhook();
```

</Tabs.Tab> </Tabs>

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.

<Tabs items={['cURL', 'Python', 'JavaScript']}> <Tabs.Tab> bash # Replace the task_id with the one you received curl http://localhost:7091/api/task_status?task_id=YOUR_TASK_ID </Tabs.Tab> <Tabs.Tab> ```python import requests import time

STATUS_URL = "http://localhost:7091/api/task_status"
task_id = "YOUR_TASK_ID"

while True:
    response = requests.get(STATUS_URL, params={"task_id": task_id})
    data = response.json()
    status = data.get("status")
    print(f"Current task status: {status}")

    if status in ["SUCCESS", "FAILURE"]:
        print("Final Result:")
        print(data.get("result"))
        break
    
    time.sleep(2)
```

</Tabs.Tab> <Tabs.Tab> ```javascript const statusUrl = 'http://localhost:7091/api/task_status'; const taskId = 'YOUR_TASK_ID';

const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));

async function pollForResult() {
  while (true) {
    const response = await fetch(`${statusUrl}?task_id=${taskId}`);
    const data = await response.json();
    const status = data.status;
    console.log(`Current task status: ${status}`);

    if (status === 'SUCCESS' || status === 'FAILURE') {
      console.log('Final Result:', data.result);
      break;
    }
    await sleep(2000);
  }
}

pollForResult();
```

</Tabs.Tab> </Tabs>