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

Patchworks callback URLs are generated in the form:

http://callbacks.wearepatchworks.com/api/v1/{{company}}/{callback_id}

For example:

https://callbacks.wearepatchworks.com/api/v1/docs_demo/01jgkwkgz5evxh253168hvevkb?patchworks_signature=ev863ew015vjhd56vg1kh2df675jh53gh12ekzkxgk1kvc8x0evwv

The {{callback_id}} element is a Patchworks signature, generated as a random hash that doesn't expire. This provides built-in authentication for our URLs however, they should still be kept private.

More about the Patchworks signature

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.

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

Step 2 Click the add new callback button:

...a unique Patchworks callback URL is generated:

Step 3 Copy this URL for use in your API requests:

Step 4 By default, the payload returned for a callback is expected in JSON format, so the content-type for callback responses will be 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:

Available formats are:

• JSON

• XML

• TXT

Payloads are not validated against this setting - it simply determines the content-type header value in responses.

Step 5 Save shape settings.

Step 6 Build the rest of your process flow as needed, including a callback shape at the point data must be returned to your API.

Step 7 Ensure that your process flow is deployed and enabled - callbacks will not be made if this isn't done.

Related pages

• The callback shape