Trigger shape (callback)
Introduction
Callback triggers are used in conjunction with the callback shape, so you can send API requests to initialise a process flow and return data in a real-time, synchronous call.
When you add a callback to a process flow trigger shape, a unique Patchworks URL is generated. This URL should be used in your API request(s), so data can be returned from the callback shape. For more information please see our callback shape page.
About Patchworks callback URLs
URLs
The structure of a callback URL includes multiple elements. Some elements are always the same, some are unique to your organisation and/or environment, and some are unique for every callback:
For example:
https://callbacks.wearepatchworks.com/api/v1/docs_demo/01k678es5y21ref5rgzszd6yvw/2?patchworks_signature=9ne4gh16n123h5z9ytmmgyt12gd6td9ehs0cf1krr5g8atsg84h5These elements are summarised below:
Base URL
This is always the same and would only change in the event of a new version of the Patchworks API being released.
Company
Your company/organisation name.
Callback ID
A unique identifier for the callback (different for every callback generated).
VE prefix
If you choose to generate trigger URLs for a virtual environment and then copy the VE URL, the prefix (i.e. internal identifier) for the selected virtual environment is included in the URL. To verify the identifier used here, you can access the corresponding virtual environment and locate the URL prefix.
Patchworks signature
A unique signature generated as a random hash (that doesn't expire). This provides built-in authentication for our URLs; however, signatures should still be kept private. The Patchworks signature is rather like an impossibly long password. To generate this, we start by generating two unique identifiers. Next, we concatenate these identifiers and shuffle the result into a never-before-seen signature. The risk of collision is one in several billion, so even if someone could guess your URL, they could never guess the signature as well.
Need to know
As noted above, the callback URL includes a signature, which (by default) is passed in as a URL parameter. However, some third-party systems do not allow URL parameters to be passed in - any that are sent are removed. In this case, Patchworks passes the signature in as a patchworks_signature header.
Adding a callback trigger
Follow the steps below to add a new callback trigger.
Access trigger shape settings
Click the settings icon associated with the trigger shape in your process flow:
(Optional) Select a virtual environment
If your callback needs to initialise a process flow that runs in a virtual environment, use the customise URLs for virtual environment selector to choose the required environment. For example:
Generate a new callback
Move down to the callbacks section and click the add new callback button. For example:
...a unique Patchworks callback URL is generated - for example:
Copy the callback URL
Use copy url OR copy ve url buttons to copy this URL, ready to paste into your third-party application.
If you selected a virtual environment in step 2, you should use the copy ve url option - this ensures that the callback triggers this process flow in the correct virtual environment.
(Optional) customise callback behaviour
By default, the payload returned for a callback is expected in JSON format, so the content-type for callback responses is set to JSON. If you require a different format, you can edit settings for the callback URL - for example:
...now you can update the expected format:
Payloads are not validated against this setting - it simply determines the content-type header value in responses.
Complete process flow development
Build the rest of your process flow as required.
Related pages
Last updated