Callback

The callback node sends workflow results to an external URL via an HTTP request. Use it to integrate Ingestly with your own backend, a custom API, or any endpoint authenticated with an API key. A following step is optional: the node can end a branch, or hand the response to the steps after it.

Sending to Business Central or QuickBooks Online? Use the dedicated Business Central or QuickBooks node instead: they add a live entity picker, a connector-specific body scaffold, and a duplicate-check safety net on top of the same delivery machinery.

Configuration

Field	Type	Required	Description
URL	string	Yes	The webhook URL to receive the results
Method	select	No	HTTP method: `POST` (default), `PUT`, or `PATCH`
Connector	select	No	An API Key, Basic Auth, OAuth 2.0, or OAuth 2.0 (Client Credentials) connector to authenticate the request. When set, its base URL prefixes the URL field and its credentials are added automatically
Write mode	select	Yes	`Insert` (default) posts the current document as a new record. `Update` writes changes back to an existing record (see Insert vs Update)
Headers	key-value editor	No	Custom headers to include in the request
Body	template editor	No	Custom body template. Defaults to the full workflow output. JSON bodies support row expansion with `$each`, `$when`, and `$case`
Body format	select	No	`JSON` (default) sends the body as `application/json`. `Binary (base64)` sends the resolved body, which must be a Base64 string, as raw bytes (see Binary body)
Timeout (seconds)	number	No	Request timeout in seconds. The send is cancelled after this many seconds. Leave blank to use the system default (45s)
Duplicate check	switch + key editor	No	Insert mode only. Names the record this step creates: a Record type label plus one or more field/value keys resolved from upstream output. When set, retries of the same step are matched by these keys rather than by the request body, so a body that changes on every attempt (a timestamp, a generated id) is still recognised as the same delivery
Destination de-duplicates by Idempotency-Key	switch	No	Off by default. Turn on only when the endpoint documents that it de-duplicates requests by the `Idempotency-Key` header. When on, a request whose response was lost is sent again with the same key instead of failing the step

Transient delivery failures are retried automatically by the platform. Use the node’s retry field to set the maximum number of attempts, between 1 and 5 (default 3).

Retries and lost responses

Every POST and PATCH carries an Idempotency-Key header that stays the same across retries of one step. What happens when a response is lost (a gateway timeout after the request left) depends on the two switches above.

On a generic connector the duplicate check cannot look the record up at the destination, so it does not recover a lost response on its own. It only fixes the identity of the delivery so a retry is never mistaken for a new one. Without Destination de-duplicates by Idempotency-Key, a lost response still fails the step, and re-running that step asks you to confirm the resend after checking the destination.

Turn Destination de-duplicates by Idempotency-Key on only when the endpoint documents idempotency keys. With it on, a lost response is resolved by sending the request again with the same key; an endpoint that ignores the header would receive the record twice.

Insert vs Update

Insert (default) posts the current document as a new record. The body defaults to the full workflow output, and you can edit it freely. Click Generate body to replace it with a starting template built from the columns carried into this step, then edit from there. Update writes changes back to an existing record through the callback’s own request. See Write-back below.

Write-back

Set Write mode to Update to write changes back to a record at the callback’s URL, instead of posting a new one. Update mode requires a Connector.

Record source

Choose where the target record’s id, and its line rows, come from. Reconcile (default, recommended). Ingestly builds the write plan from an upstream Reconcile step’s verified match, and keeps its safety gate.

Field	Type	Required	Description
Reconcile node	select	Yes	The upstream reconcile step whose approved values are written back. You need a reconcile node upstream, or this selector is empty
Record id path (under Advanced)	template editor	Yes	The path to the record’s unique id, read at run time to target the update. For example, use `{{value[0].id}}` for a collection response or `{{id}}` for a single record
Line id path (under Advanced)	template editor	No	The path to a matched connector line’s unique id inside the record source, scoped to that single line row, not the whole record
Line id column (under Advanced)	text	No	The output key the matched line’s id is written under, so the body can read it back as `{{$item.<name>}}`

Unlike Business Central and QuickBooks, a callback has no connector or entity, so Line id path and Line id column have no default here: both render blank until you fill them in. The server stamps a matched or removed line row’s connector line id only when both are set, reading the id from Line id path and writing it under the Line id column key. If you leave them blank, every line operation’s id resolves to nothing, silently: the step still runs, but {{$item.lineId}} (or whatever name you gave Line id column) is empty in the body. If your Reconcile-source Update writes line items, fill in both fields yourself.

Two safety behaviors apply: if the reconcile result has a blocking mismatch and no approved review, the step fails instead of writing; if nothing changed (an empty write set), the step succeeds without sending a request.

Direct (opt-in). No Reconcile node needed. You supply the record id, and optionally the line arrays, directly.

Field	Type	Required	Description
Record id	template editor	Yes	Any template expression that resolves to the target record’s id, for example an id extracted from the document or returned by an earlier lookup step
Lines	template editor	No	An upstream array whose rows already carry a connector line id. Each row becomes a line update
Added lines	template editor	No	An upstream array of new lines to create. These rows have no line id yet
Removed lines	template editor	No	An upstream array whose rows already carry a connector line id. Each row becomes a line delete
Line id field	text	Yes when Lines or Removed lines is bound	The row field that holds the connector line id, for example `lineId`

Direct skips the Reconcile safety gate: whatever record id and line references resolve above are written as-is, with nothing verifying them against the source document first. Switch to Reconcile when that verification matters.

For line pairing too complex for a template to express (for example, matching document lines to fetched connector lines by more than one key), add a Transform step upstream that joins the two sides and emits rows carrying both, then point Direct’s Lines field at that array.

Direct never fetches the target record, so {{$writeback.record.*}} has nothing to read: a body that references it under Direct is a design-time error. Bind any field you need (an ETag, a concurrency token) from whichever upstream node already supplied the record id instead.

The write plan

At run time, Ingestly resolves the write plan and exposes it to the body template under the {{$writeback}} head:

{{$writeback.recordId}}: the target record’s id.
{{$writeback.record.*}}: any field of the fetched connector record (Reconcile source only; empty under Direct), for example {{$writeback.record.updatedAt}}.
{{$writeback.updates}}, {{$writeback.adds}}, {{$writeback.removes}}: arrays of matched, added, and removed line rows. Iterate them in a JSON body with $each, for example "$each": "{{$writeback.updates}}".

Use {{$writeback.*}}, not {{writeback.*}}. There is no reserved bare writeback head: an unprefixed reference is an ordinary node reference and fails if no node named writeback exists upstream. The $ prefix is what lets a workflow also have a node named writeback with no ambiguity.

Unlike the Business Central and QuickBooks nodes, a callback has no connector or entity, so its auto-generated Update body is a plain shape rather than an operations document:

{
  "id": "{{$writeback.recordId}}",
  "customerName": "{{payload.customerName}}",
  "lines": [
    { "$each": "{{$writeback.updates}}", "quantity": "{{$item.quantity}}" },
    { "$each": "{{$writeback.adds}}", "quantity": "{{$item.quantity}}" }
  ]
}

The Advanced body editor lets you reshape the request around your endpoint’s own field names, and add a third $each block over {{$writeback.removes}} if your endpoint accepts deletions: the generated body does not wire that one in by default.

Binary body

Set Body format to Binary (base64) to send the request body as raw bytes instead of JSON. The body template must resolve to a Base64 string, typically exactly {{$document.file.base64}} (the source document).

Ingestly decodes the Base64 string and sends the resulting bytes as the request body.
The content type defaults to application/octet-stream. Set a Content-Type header to override it.
GET and DELETE requests never send a body.
If the resolved body is not valid Base64, the step fails with a clear error instead of sending malformed bytes.

The raw bytes and the Base64 text are never persisted: the request history records a binary body as [binary N bytes, type].

Dry run behavior

On a Dry run, the callback node does not send the HTTP request. Instead, the run output shows a preview with:

The resolved request URL
The resolved request headers
The rendered request body

Use a dry run to verify callback templates before you send live outputs.

Inputs and outputs

Allowed inputs: Any action node that produces a result payload (extract, review, validation, transform, merge, parse, wait, if, switch, loop, variable, store, reconcile, prompt, HTTP, call workflow, Business Central, QuickBooks), the sub-workflow trigger, and another callback node (see Chaining callbacks). Filter, split and classify are not among them: they select pages rather than produce a result to send, so put the node that produces the data between them and the callback. Output: Sends an HTTP request to the configured URL with the workflow results.

Using the result downstream

Your endpoint’s response body becomes the node’s payload directly. If it replies {"ticketId":"T-1001"}, then {{NodeName.payload.ticketId}} resolves to T-1001. Ingestly does not wrap or rename those keys, because they belong to the receiving system rather than to Ingestly. Autocomplete can advertise part of that shape ahead of any run. With Body format set to OData Batch, it offers the full payload.responses[] shape (id, status, headers, body per operation), because the batch response envelope is fixed. With a JSON body and a Connector attached, it offers payload.id, the created record’s id: that is a hint, and your endpoint has to actually return the field. For any other key your endpoint returns, the shape is not known until a run has produced a sample.

Chaining callbacks

A callback node accepts another callback as its input. The second callback reads the first one’s response by node name, the same way it reads any upstream node: if the first callback is named ticket and its endpoint replied {"ticketId":"T-1001"}, the second callback’s body can use {{ticket.payload.ticketId}}. A callback body has to name its source node: a bare {{payload}} shorthand is not resolved in a callback body. metadata.callback - request-level information:

Field	Description
statusCode	The HTTP response status code
requestSucceeded	Whether the request returned a 2xx status
url	The URL that was actually called. Emitted on every run but not offered by autocomplete; type it by hand
method	The HTTP method that was used, in upper case (`POST`, `PATCH`, and so on), or `NONE` when an Update had nothing to send
attempts	The retry attempt number for this request. Emitted but not offered by autocomplete

An Update with nothing to send (the reconcile found no changes) makes no request at all. The step succeeds with a null payload, statusCode 204 and method NONE.

A following step is optional. The node is still an output: it stays in the Outputs group in the node picker, and it cannot be disabled.

Error output

Turn on Error output in the node’s settings to add a second port. When the write fails after its retries, the run follows that port instead of failing, so you can route the failure to a Review, a notification, or a compensating step. With no error edge drawn, a failed write fails the run exactly as before.

Webhooks and callbacks guide

Payload format, verification, and integration patterns

Webhook signing keys

Verify webhook signatures for security

Business Central

Dedicated node for Business Central destinations

QuickBooks

Dedicated node for QuickBooks Online destinations

Getting started

Learn

Guides

Reference

Administration

Configuration

Retries and lost responses

Insert vs Update

Write-back

Record source

The write plan

Binary body

Dry run behavior

Inputs and outputs

Using the result downstream

Chaining callbacks

Error output

Webhooks and callbacks guide

Webhook signing keys

Business Central

QuickBooks

​Configuration

​Retries and lost responses

​Insert vs Update

​Write-back

​Record source

​The write plan

​Binary body

​Dry run behavior

​Inputs and outputs

​Using the result downstream

​Chaining callbacks

​Error output

​Related

Webhooks and callbacks guide

Webhook signing keys

Business Central

QuickBooks

Configuration

Retries and lost responses

Insert vs Update

Write-back

Record source

The write plan

Binary body

Dry run behavior

Inputs and outputs

Using the result downstream

Chaining callbacks

Error output

Related