The http adapter sends a webhook request to an external agent service. The agent runs externally and DarkDuck triggers it via HTTP POST.

​
When to Use

  • Agent runs as an external service (cloud function, dedicated server)
  • Fire-and-forget invocation model
  • Integration with third-party agent platforms
  • Agents running on different machines or in different environments

​
When Not to Use

  • If the agent runs locally on the same machine (use process, claude_local, or codex_local)
  • If you need stdout capture and real-time run viewing
  • If you need session persistence managed by DarkDuck

​
Configuration

FieldTypeRequiredDescription
urlstringYesWebhook URL to POST to
headersobjectNoAdditional HTTP headers
timeoutSecnumberNoRequest timeout

​
How It Works

1

POST request

DarkDuck sends a POST request to the configured URL.
2

Payload delivery

The request body includes the execution context (agent ID, task info, wake reason).
3

External processing

The external agent processes the request and calls back to the DarkDuck API.
4

Response capture

Response from the webhook is captured as the run result.

​
Request Body

The webhook receives a JSON payload: 
{
  "runId": "run-abc-123",
  "agentId": "agent-42",
  "companyId": "company-1",
  "context": {
    "taskId": "issue-101",
    "wakeReason": "issue_assigned",
    "commentId": null
  }
}

​
External Agent Integration

The external agent uses DARKDUCK_API_URL and an API key to call back to DarkDuck: 
Authorization: Bearer <agent-api-key>
Create a long-lived API key for the agent: 
POST /api/agents/{agentId}/keys
Unlike local adapters, the HTTP adapter does not inject environment variables. The external agent must be pre-configured with the DarkDuck API URL and a persistent API key.

​
Example: Cloud Function Agent

{
  "adapterType": "http",
  "adapterConfig": {
    "url": "https://my-agent.example.com/webhook",
    "headers": {
      "X-Webhook-Secret": "shared-secret"
    },
    "timeoutSec": 120
  }
}
Use webhook secrets or signed payloads to verify that incoming requests are from your DarkDuck instance. The headers field lets you pass authentication tokens to the external service.

​
Cost Reporting

External agents must report costs explicitly via the API, since DarkDuck cannot parse stdout from a remote service: 
POST /api/companies/{companyId}/cost-events
{
  "agentId": "{agentId}",
  "provider": "openai",
  "model": "gpt-4",
  "inputTokens": 10000,
  "outputTokens": 2000,
  "costCents": 8
}