Use Async Flow when Link manages the overall flow, but an itinerary step delegates processing to an external system. Link persists the message and its continuation point; the external system later reports its result through this callback API.
For flows controlled entirely outside Link, use the External Flow Tracking APIs instead. Async Tracking records events later; it does not resume an itinerary.
Prerequisites
-
Configure the step for Async Flow and agree whether the callback body replaces the message payload and whether callback headers become context properties. See the existing Async HTTP itinerary step guide for step setup.
-
Give the callback user API AsyncFlow Send Callback (
API_AsyncFlow_Callback), included in the API Asynchronous Flow role. Authentication uses the shared REST setup described in API Conventions, including theapiscope. -
Make the callback URL reachable from the external service. Link supplies it through
X-Link-Callback-Urlin the outgoing HTTP request.
The correlation ID identifies a pending flow; it is not an authentication credential. The callback operation checks its API permission and does not apply an additional caller-partner filter to the correlation lookup.
Request and callback sequence
-
Link persists the message and continuation point, then invokes the external HTTP service. The request includes
X-Link-Correlation-IdandX-Link-Callback-Url. -
The external service retains those values with its work item and returns a successful initial HTTP response. That response acknowledges the initial request; the later callback carries the processing result.
-
When processing finishes, send
POST /api/rest/operation/async/callbackto the supplied callback address, using the original correlation ID and the result headers below. -
Link either resumes the saved continuation or handles the reported failure. A successful callback response acknowledges this handling, not completion of all remaining itinerary steps.
Use the correlation ID from the request unchanged. Do not substitute a document ID, document GUID, or a newly generated GUID.
Callback headers and body
|
Header |
Meaning |
|---|---|
|
|
Required: identifies the persisted flow |
|
|
Required: |
|
|
Media type of the returned payload when its body is used as the new message |
|
|
Optional Link error code for a failed result; use a code agreed with the Link configuration owner |
|
|
Optional explanation of a failed result |
|
|
Optional document status for a failed result |
|
|
Optional HTTP-header context property, applied on a successful result when promotion of async response headers is enabled |
The body contains the raw processing result, not a JSON envelope describing the callback. When Use async response body as new message is enabled, an OK callback must contain a nonempty body. That setting defaults to enabled in this implementation. When disabled, Link retains the saved payload. The returned content type is used with a replacement payload.
For Failed, Link handles the error rather than resuming the normal continuation. Without a recognized X-Link-Document-Status, it reports Failed; an unrecognized supplied status is also recorded as a technical status. A recognized document status is used instead. Configured error rules can affect the resulting tracking state. Error and document-status headers do not override the successful path when X-Link-Status is OK.
Example: return processed data
Set the callback address and correlation ID to the values received from Link. Assume the external service has written its result to ./processed-order.xml and the step is configured to use that result as the new payload.
CALLBACK_URL='https://<your-link-api-host>/api/rest/operation/async/callback'
CORRELATION_ID='<X-Link-Correlation-Id received from Link>'
LINK_PAT='<your-personal-access-token>'
curl --silent --show-error --fail-with-body --include \
--user ":${LINK_PAT}" \
--header "X-Link-Correlation-Id: ${CORRELATION_ID}" \
--header 'X-Link-Status: OK' \
--header 'Content-Type: application/xml' \
--data-binary '@./processed-order.xml' \
"${CALLBACK_URL}"
A processed callback returns 200 with:
{
"callbackSuccessful": true,
"errorCode": null,
"errorText": null
}
Link records AsyncResponseReceived and queues the message for its saved continuation. Continue monitoring the flow in Link; the callback does not wait for the remaining itinerary to finish.
Alternative: report a processing failure
If external processing failed, send this instead of the successful callback. Set ERROR_CODE to an agreed code. A failure callback does not require a result body.
ERROR_CODE='<agreed-Link-error-code>'
curl --silent --show-error --fail-with-body --include \
--request POST \
--user ":${LINK_PAT}" \
--header "X-Link-Correlation-Id: ${CORRELATION_ID}" \
--header 'X-Link-Status: Failed' \
--header "X-Link-Error-Code: ${ERROR_CODE}" \
--header 'X-Link-Error-Text: The external service could not process the order' \
"${CALLBACK_URL}"
Successful handling of this failure also returns 200 with callbackSuccessful: true. It means Link handled the reported failure, not that the external processing succeeded. If no error code is supplied, Link uses its default callback-failure code.
Callback errors and flow effects
The callback action returns its own JSON fields: callbackSuccessful, errorCode, and errorText. These differ from the shared REST exception envelope. Authentication and permission failures can still use the common formats.
|
Result |
Effect |
|---|---|
|
400, missing correlation ( |
No pending flow is selected |
|
400, unknown correlation ( |
No matching pending flow was found; this can also follow an already handled callback |
|
400, missing status ( |
An identified pending flow is handled as a failure and its waiting record is removed |
|
400, empty body when an OK result requires one ( |
The identified pending flow is handled as a failure and its waiting record is removed |
|
Other 400 or 500 |
Processing or logging failed; some effects may already have occurred |
Validate the result headers and required body before sending. In particular, 400 does not guarantee that the flow is still waiting for a corrected callback.
Repeated callbacks and uncertain outcomes
After normal success or failure handling, Link removes the pending record for that correlation ID. A subsequent callback normally receives unknown correlation rather than the previous result. This is not an idempotent replay contract, and an unknown-correlation response alone does not prove what the first callback did.
Send one final result per correlation and avoid concurrent duplicate callbacks. After a timeout or error, retain the correlation ID and inspect Link tracking and the AsyncFlow log before retrying. Resumption includes deleting the pending record, queuing the continuation, and saving a callback log; the API does not expose an atomic acknowledgement or exactly-once guarantee across those effects. An error response can therefore follow a flow that has already resumed or failed.
GET /api/rest/operation/async only returns an endpoint status message. It is not a query for a correlation's processing state. The controller exposes no polling or cancellation operation for pending flows.