# 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.&#x20;

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).&#x20;

## 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**&#x20;

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.&#x20;

{% 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.&#x20;

{% 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.&#x20;
{% endhint %}
{% endstep %}
{% endstepper %}

## Related pages

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-callback.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.