> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-callback.md).

# Trigger shape (callback)

## Introduction

`Callback` triggers are used in conjunction with the [callback shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/callback-shape.md), 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](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape.md), 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](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/callback-shape.md). For more information, please see our [callback shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/callback-shape.md) page.

{% hint style="info" %}
Callbacks won't be initialised until the associated process flow is [deployed](/product-documentation/process-flows/building-process-flows/process-flow-versioning.md#deploying-a-draft-or-inactive-version) and [enabled](/product-documentation/process-flows/managing-process-flows/enabling-and-disabling-a-process-flow/enabling-and-disabling-a-process-flow-without-virtual-enviroments.md).
{% 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:

<div align="left"><figure><img src="/files/qd6sDz72zcV6eNbI2ikd" alt=""><figcaption></figcaption></figure></div>

For example:

{% code overflow="wrap" %}

```
https://callbacks.wearepatchworks.com/api/v1/docs_demo/01k678es5y21ref5rgzszd6yvw/2?patchworks_signature=9ne4gh16n123h5z9ytmmgyt12gd6td9ehs0cf1krr5g8atsg84h5
```

{% endcode %}

These elements are summarised below:

<table><thead><tr><th width="230.54296875">Callback URL element</th><th>Summary</th></tr></thead><tbody><tr><td>Base URL</td><td>This is always the same and would only change in the event of a new version of the Patchworks API being released.</td></tr><tr><td>Company</td><td>Your company/organisation name.</td></tr><tr><td>Callback ID</td><td>A unique identifier for the callback (different for every callback generated).</td></tr><tr><td>VE prefix</td><td>If you choose to <a href="#adding-a-trigger-webhook">generate trigger URLs for a virtual environment and then copy the VE URL</a>, 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<a href="/pages/SiWXnE8YVuWBDKUA7NFW"> the URL prefix</a>.</td></tr><tr><td>Patchworks signature</td><td>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.<br><br>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.</td></tr></tbody></table>

## 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](/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.md).

## 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:

<div align="left"><figure><img src="/files/Ek7UgW5eoqMZigMcvgV7" alt="" width="367"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**(Optional) Select a virtual environment**

If your callback needs to initialise a process flow that runs in a [virtual environment](/product-documentation/virtual-environments/about-virtual-environments.md), use the `customise URLs for virtual environment` selector to choose the required environment. For example:

<div align="left"><figure><img src="/files/UrDE7mYSJdHSlgNLadhv" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
If you don't use [virtual environments](/product-documentation/virtual-environments/about-virtual-environments.md), 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:

<div align="left"><figure><img src="/files/pj0QANE4bIW885Uuq5HY" alt="" width="375"><figcaption></figcaption></figure></div>

...a unique [Patchworks callback URL](#about-patchworks-callback-urls) is generated - for example:

<div align="left"><figure><img src="/files/UDSE7XkB728FPrsnDa5w" alt="" width="375"><figcaption></figcaption></figure></div>
{% 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:

<div align="left"><figure><img src="/files/rjyMJCpa26OR241yQRvv" alt="" width="375"><figcaption></figcaption></figure></div>

...now you can update the expected format:

<div align="left"><figure><img src="/files/quCLqoJQOBs4HayxvTyE" alt="" width="375"><figcaption></figcaption></figure></div>

{% 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](/product-documentation/process-flows/building-process-flows/process-flow-versioning.md#deploying-a-draft-or-inactive-version) and [enabled](/product-documentation/process-flows/managing-process-flows/enabling-and-disabling-a-process-flow/enabling-and-disabling-a-process-flow-without-virtual-enviroments.md). Callbacks will not be made if this isn't done.
{% endhint %}
{% endstep %}
{% endstepper %}

## Related pages

* [The callback shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/callback-shape.md)