This is preview documentation for functionality that will be introduced in our next scheduled release. Information on this page is subject to change until this time.
The Callback feature allows you to send an API request which initialises a process flow and returns data in a real-time, synchronous call.
This means you can incorporate process flows in your online systems where instant data retrieval is needed - for example, as part of an online checkout process (check inventory levels, find delivery lockers, check gift card balances, etc.).
Implementing a callback shape requires two elements:
Callback trigger. Similar to webhooks, callback triggers are unique Patchworks URLs you can use in API calls to trigger the associated process flow and receive callback data.
Callback shape. Add this shape to your process flow at the point you want incoming data to be returned.
Your process flow must include a callback trigger (a unique Patchworks URL generated from the trigger shape) and a callback shape (placed in the flow at the point you want data returned to your API).
When you send a GET or POST request to the Patchworks callback trigger URL, the associated process flow is initialised - a callback connection is opened and all shapes up to the FIRST callback shape are processed in a dedicated callback queue. This queue takes priority over all other queues, ensuring that any processing needed to obtain callback data is completed at maximum speed.
When the callback shape is reached, current data is returned (the content-type header for this data is set via settings for the callback trigger). If multiple payloads are passed into the callback shape, they are returned as an array.
Once the payload is returned, the callback connection is closed and any subsequent shapes are processed via normal queues. This process is shown below:
All customers access the same callback queue, so performance depends on the complexity of your process flows and general platform load.
For faster speeds, a dedicated callback queue can be purchased for your company. Please contact our Sales team for details.
A Patchworks bolt-on is required to use callbacks - please contact us for pricing information.
A callback can only be made if the process flow is enabled and deployed.
For a callback to work, your process flow must include both a callback trigger and a callback shape.
If a process flow includes a callback trigger but no callback shape, the flow runs normally (without errors or warnings). However, with no mechanism to determine when/what data to return, the callback connection stays open for 60 seconds and closes when no payload is found.
If a process flow includes a callback shape but no callback trigger, the flow won't have an initiating URL for returning payload data from the callback shape. The flow runs normally (without errors or warnings) but no data is returned.
When a process flow is initialised with a callback trigger, a callback connection is opened and we check for a returned payload every 200 milliseconds. If no payload is found within 60 seconds, the connection is closed.
You can send GET and POST requests to a callback trigger.
If multiple payloads are passed into a callback shape, they are returned in an array.
A process flow can include multiple callback shapes however these should be placed with care to ensure optimal performance - see Best practice for callback shape placement for more information.
To initialise a process flow via a callback, you add one or more callbacks to the trigger shape - for example:
This unique URL should be copied and used in your API requests. For information about working with the trigger shape, see Trigger shape (callback).
Callback shapes are added in the usual way - build your process flow to the point you want data to be returned, and add a callback shape from the shapes palette:
The callback shape is an 'opt-in' advanced feature. If your subscription includes advanced features and you'd like to use callbacks, please contact us to enable it.
Having added a callback shape to your process flow, click the settings icon:
Now you can choose a response code to be returned:
Available response codes are:
200
OK
201
Created
400
Bad request
The essence of a callback shape is returning required data as fast as possible, so we need all shapes leading up to it to be processed quickly. The priority callback queue helps with this, but there are a couple of process flow design points to keep in mind for optimal performance.
With the default 60-second callback connection window in mind, we advise keeping the path up to your callback shape as lean and efficient as possible - the more shapes placed before a callback shape, the greater the chance of a timeout.
Before a callback shape, focus only on getting data that needs to be returned and then handle anything else in the flow after the callback shape.
The callback connection window can be increased from 60 seconds to a maximum of 120 seconds - please log a request with the Patchworks support team if this is required.
All shapes up to the FIRST callback shape are processed via the priority callback queue. A process flow can include as many callback shapes as you like however, once the FIRST callback shape is hit, all subsequent shapes (including additional callback shapes) are processed via standard queues. This is shown below:
Process flow runs triggered from a callback are logged in the usual way, with the triggered by type set to callback - for example:
When data is returned via a callback, a Pw-Flow_Run response header is included, where the value is the flow run id - for example:
You can use this to search for the associated entry in run logs and view details for the run:
