Callback shape

Introduction

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.

A single incoming payload for any process flow shape should not exceed 500MB.

We recommend processing multiple, smaller payloads rather than one single payload (1000 x 0.5MB payloads are more efficient than 1 x 500MB payload!).

For payloads up to 500MB, consider adding a flow control shape to batch data into multiple, smaller payloads. Payloads exceeding 500MB should be batched at source.

How it works

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, your company can purchase a dedicated callback queue. Please contact our Sales team for details.

Need to know

• 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.

• All callback responses are contained 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.

Callback trigger

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 shape

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:

Code	Description
200	OK
201	Created
400	Bad request

By default, if a callback shape receives multiple payloads, these are output as a single array. The first payload option can be toggled on if you only want to return the first payload received:

For sample responses, see our callback responses section below.

Best practice for callback shape placement

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.

Callback connection window

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.

Multiple callback shapes in a flow

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:

Callback responses

By default, callback responses are always returned in an array. Where multiple payloads/pages are generated (e.g. where data is paginated or passed through flow control), each payload/page is returned within that initial array. JSON and XML sample responses are shown below.

You can change the behaviour for multiple payloads using the return first payload option. If this option is togged on and the callback shape receives multiple payloads, only the first payload is returned (without the initial array).

Sample responses for all scenarios are provided below:

• JSON - single payload/page
• JSON - multi payload/page (default)
• JSON - multi payload/page (return first payload ON)
• XML - single payload/page
• XML - multi payload/page (default)
• XML - multi payload/page (return first payload ON)

JSON

Single payload/page response

[
    [
        {
            "first_name": "Izzy",
            "last_name": "Smith"
        }
    ]
]

Multi payload/page response (default)

[
    [
        {
            "first_name": "Izzy",
            "last_name": "Smith"
        }
    ],
    [
        {
            "first_name": "Tom",
            "last_name": "Smith"
        }
    ]
]

Multi payload/page response (return first page ON)

[
    {
        "first_name": "Izzy",
        "last_name": "Smith"
    }
]

XML

Single payload/page response

[<results><group><person><first_name>Izzy</first_name><last_name>Smith</last_name></person></group></results>
]

Multi payload/page response (default)

[<results><group><person><first_name>Izzy</first_name><last_name>Smith</last_name></person></group></results>,<results><group><person><first_name>Tom</first_name><last_name>Smith</last_name></person></group></results>
]

Multi payload/page response (return first page ON)

<results><group><person><first_name>Izzy</first_name><last_name>Smith</last_name></person></group></results>

Callback limits

The number of callback requests permitted per minute is determined by your core subscription tier. Given the nature of callbacks, soft and hard limits apply for requests:

• Soft limit If a callback request exceeds your allowance up to and including the hard limit (see below) then processing continues normally, subject to any overage agreement that's in place.

• Hard limit A hard limit of 240 applies globally. If the number of callback requests made per minute exceeds the associated subscription tier allowance by 241 or more, the request fails with a 429 too many requests response.

Troubleshooting callbacks

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: