# Trigger shape (callback) ## Introduction `Callback` triggers are used in conjunction with the [callback shape](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/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](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/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](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/callback-shape). For more information, please see our [callback shape](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/callback-shape) page. {% hint style="info" %} Callbacks won't be initialised until the associated process flow is [deployed](https://doc.wearepatchworks.com/product-documentation/process-flows/process-flow-versioning#deploying-a-draft-or-inactive-version) and [enabled](https://doc.wearepatchworks.com/product-documentation/process-flows/managing-process-flows/enabling-and-disabling-a-process-flow/enabling-and-disabling-a-process-flow-without-virtual-enviroments). {% endhint %} ## 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: {% code overflow="wrap" %} ``` https://callbacks.wearepatchworks.com/api/v1/docs_demo/01k678es5y21ref5rgzszd6yvw/2?patchworks_signature=9ne4gh16n123h5z9ytmmgyt12gd6td9ehs0cf1krr5g8atsg84h5 ``` {% endcode %} These elements are summarised below:
Callback URL elementSummary
Base URLThis is always the same and would only change in the event of a new version of the Patchworks API being released.
CompanyYour company/organisation name.
Callback IDA unique identifier for the callback (different for every callback generated).
VE prefixIf 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 signatureA 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](#urls), 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 and remove any that are received. In this case, a `patchworks-signature` header can be used. For details, please refer to: [Passing the Patchworks signature as a header for callback requests](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-callback/passing-the-patchworks-signature-as-a-header-for-callback-requests). ## Adding a callback trigger Follow the steps below to add a new `callback` trigger. {% stepper %} {% step %} **Access trigger shape settings** Click the `settings` icon associated with the `trigger` shape in your process flow:
{% endstep %} {% step %} **(Optional) Select a virtual environment** If your callback needs to initialise a process flow that runs in a [virtual environment](https://doc.wearepatchworks.com/product-documentation/virtual-environments/about-virtual-environments), use the `customise URLs for virtual environment` selector to choose the required environment. For example:
{% hint style="info" %} If you don't use [virtual environments](https://doc.wearepatchworks.com/product-documentation/virtual-environments/about-virtual-environments), ignore this option. {% endhint %} {% endstep %} {% step %} **Generate a new callback** Move down to the `callbacks` section and click the `add new callback` button. For example:
...a unique [Patchworks callback URL](#about-patchworks-callback-urls) is generated - for example:
{% endstep %} {% step %} **Copy the callback URL** Use `copy url` OR `copy ve url` buttons to copy this URL, ready to paste into your third-party application. {% hint style="warning" %} 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. {% endhint %} {% endstep %} {% step %} **(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:
{% hint style="warning" %} Payloads are not validated against this setting - it simply determines the `content-type` header value in responses. {% endhint %} {% endstep %} {% step %} **Complete process flow development** Build the rest of your process flow as required. {% hint style="info" %} When you're ready, ensure that your process flow is [deployed](https://doc.wearepatchworks.com/product-documentation/process-flows/process-flow-versioning#deploying-a-draft-or-inactive-version) and [enabled](https://doc.wearepatchworks.com/product-documentation/process-flows/managing-process-flows/enabling-and-disabling-a-process-flow/enabling-and-disabling-a-process-flow-without-virtual-enviroments). Callbacks will not be made if this isn't done. {% endhint %} {% endstep %} {% endstepper %} ## Related pages * [The callback shape](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/callback-shape)