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.

Callbacks won't be initialised until the associated process flow is deployed and enabled.

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=9ne4gh16n123h5z9ytmmgyt12gd6td9ehs0cf1krr5g8atsg84h5

These elements are summarised below:

Callback URL element
Summary

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.

Adding a callback trigger

Follow the steps below to add a new callback trigger.

1

Access trigger shape settings

Click the settings icon associated with the trigger shape in your process flow:

2

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

If you don't use virtual environments, ignore this option.

3

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:

4

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.

5

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

6

Complete process flow development

Build the rest of your process flow as required.

When you're ready, ensure that your process flow is deployed and enabled. Callbacks will not be made if this isn't done.

Related pages

PreviousTrigger shape (webhook)NextTrigger shape (event listener)

Last updated