HTTP Steps

Configure HTTP endpoints, methods, timeouts, and URL placeholders. Includes the execution context headers (Argyll-Flow-ID, Argyll-Step-ID, Argyll-Receipt-Token, Argyll-Webhook-URL) and how the engine treats 4xx versus 5xx responses.

HTTP Step Basics

HTTP Steps call external services. Choose between sync and async based on how your service behaves.

Method and Endpoint

Specify the HTTP method and endpoint URL. You can use placeholders for required inputs:

{
  "http": {
    "method": "GET",
    "endpoint": "https://api.example.com/users/{user_id}/profile",
    "timeout": 5000
  }
}

Argyll resolves placeholders before calling the endpoint.

Input Mapping

For GET requests, required inputs go into the URL. For POST/PUT, they go into the JSON body:

{
  "http": {
    "method": "POST",
    "endpoint": "https://api.example.com/orders",
    "timeout": 5000
  },
  "attributes": {
    "customer_id": { "role": "required" },
    "items": { "role": "required" },
    "order_id": { "role": "output" }
  }
}

Response Handling

Successful responses return output arguments directly. HTTP status codes and Problem Details indicate failures. Argyll handles retries based on Step configuration.

Headers and Context

Argyll sends execution context in request headers:

• Argyll-Flow-ID: The Flow ID
• Argyll-Step-ID: The Step ID
• Argyll-Receipt-Token: Unique token for this Work Item (use for idempotency)
• Argyll-Webhook-URL: Callback URL for async steps

Async Steps

Async steps initiate work and return immediately. The service calls back to Argyll-Webhook-URL when done:

{
  "id": "process-payment",
  "type": "async",
  "http": {
    "method": "POST",
    "endpoint": "https://api.example.com/payments/capture",
    "timeout": 1000
  }
}

The timeout on an async Step governs only the initial HTTP request, not how long to wait for the callback.

Failure Responses

Return a non-2xx status with application/problem+json to signal failure:

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Customer not found"
}

HTTP 4xx responses are permanent failures (no retry). HTTP 5xx and transport errors are retryable.