httpRequest

The httpRequest output ships records to an HTTP destination. Two request modes: batch (everything that reached the output in one request) or single (one request per record). Supports retries, authentication, and custom success conditions.

Minimal example

output:
  type: httpRequest
  endpoint: https://destination.example.com/api/orders/import
  method: POST
  requestMode: batch

Options

property	type	default	description
typerequired	"httpRequest"	—	Module type discriminator. Must be `httpRequest` for this module.
id	string	—	Unique identifier within the pipeline.
name	string	—	Human-readable name.
description	string	—	—
enabled	boolean	true	Whether module is active.
tags	array<string>	—	—
onError	string	"fail"	Default error action. Case-insensitive; normalized to lowercase by the runtime.
endpointrequired	string	—	HTTP endpoint URL. Templates are accepted; the final URL is validated at runtime after template resolution.
method	object	—	—
headers	map<string, string>	—	—
queryParams	map<string, string>	—	Query parameters.
body	string	—	Inline request body. Templates ({{record.field}}) are evaluated at runtime. The body is sent regardless of the HTTP method.
bodyTemplateFile	string	—	Path to an external template file used as the request body. Mutually exclusive with `body` is not enforced; if both are set, the inline body wins.
authentication	union (4 variants)	—	—
timeoutMs	integer	—	Request timeout in milliseconds. When omitted, each module applies its own runtime default.
success	object	—	—
retry	object	—	—
keys	array<object>	—	List of key configurations for extracting values from records and using them in path, query, or headers.
requestMode	string	"batch"	Request mode: 'batch' (all records in one request, default) or 'single' (one request per record). batchsingle

Request mode

requestMode: batch       # one request with all records (default)
requestMode: single      # one request per record

Mode	When to use
`batch`	Destination accepts arrays — fewer requests, lower overhead.
`single`	Destination only accepts one record at a time, or you need per-record templating in the URL.

In single mode, you can template the URL with {{record.x}}:

endpoint: https://destination.example.com/api/orders/{{record.id}}
method: PUT
requestMode: single

The URL is resolved once per record, then the runtime fires one request for each.

Success conditions

By default, Cannectors considers status codes 200, 201, 202, 203, and 204 as success. Override via the success block:

success:
  statusCodes: [200, 201, 202]

You can also evaluate an expr expression against the response. The variables statusCode (int), headers (map), and body (parsed JSON if applicable) are exposed:

success:
  expression: 'statusCode == 200 && body.status == "ok"'

When both statusCodes and expression are set, both must hold for the request to count as successful.

Templating

The body, headers, and URL path (in single mode) all support {{record.<path>}} templates. They're substituted at request time, once per record.

output:
  type: httpRequest
  endpoint: https://destination.example.com/api/customers/{{record.id}}
  method: PUT
  requestMode: single
  body: |
    {
      "id": "{{record.id}}",
      "email": "{{record.email}}",
      "tier": "{{record.tier}}"
    }

Or, for larger templates, externalize the body:

bodyTemplateFile: ./templates/customer-import.json

Examples

examples/19-http-output-single-template.yaml— single mode + body templateview source ↗

19-http-output-single-template.yaml

name: http-output-single-template
version: 1.0.0
description: Send one templated HTTP request per record with path, query, and header keys.
tags:
  - http-output
  - body-template
input:
  type: httpPolling
  schedule: "*/10 * * * *"
  endpoint: https://source.example.com/api/tasks
  dataField: tasks
filters:
  - type: remove
    target:
      - internal
      - debug
output:
  type: httpRequest
  endpoint: https://destination.example.com/api/projects/{projectId}/tasks/{{record.id}}
  method: PUT
  requestMode: single
  bodyTemplateFile: examples/assets/templates/task_update.json
  queryParams:
    source: cannectors
  keys:
    - field: project.id
      paramType: path
      paramName: projectId
    - field: updatedAt
      paramType: query
      paramName: updated_at
    - field: tenantId
      paramType: header
      paramName: X-Tenant-Id
  headers:
    Content-Type: application/json
    X-Trace-Source: "{{record.source | default: \"unknown\"}}"
  success:
    statusCodes:
      - 200
      - 204

examples/20-http-output-retry-auth-api-key.yaml— retry + API key authview source ↗

20-http-output-retry-auth-api-key.yaml

name: http-output-retry-auth-api-key
version: 1.0.0
description: Send records with API key authentication and output retry handling.
tags:
  - http-output
  - retry
input:
  type: httpPolling
  schedule: "*/5 * * * *"
  endpoint: https://source.example.com/api/shipments
  dataField: shipments
filters:
  - type: condition
    expression: id != nil
    else:
      - type: drop
output:
  type: httpRequest
  endpoint: https://destination.example.com/api/shipments
  method: POST
  requestMode: batch
  authentication:
    type: api-key
    credentials:
      key: ${DESTINATION_API_KEY}
      location: header
      headerName: X-API-Key
  retry:
    maxAttempts: 3
    delayMs: 500
    backoffMultiplier: 2
    maxDelayMs: 5000
    retryableStatusCodes:
      - 408
      - 429
      - 500
      - 502
      - 503
      - 504
    useRetryAfterHeader: true
    retryHintFromBody: body.retryable == true
  success:
    statusCodes:
      - 200
      - 201
      - 202

httpRequest

Minimal example

Options

Request mode

Success conditions

Templating

Examples

Cross-references

Authentication

Retry & error handling

database output

On this page