Trigger shape (webhook)

Introduction

The trigger webhook option can be used if you want to trigger a process flow whenever a given event occurs in your third-party application.

When you choose to add a webhook to a process flow trigger shape, a Patchworks webhook URL with built-in authentication is auto-generated. This URL must be added to your third-party application, so it knows where to send event data.

How you use webhooks is driven by your business requirements, and the capabilities of your third-party application. For example, your third-party application might send a POST request to a webhook which includes a batch of orders to be processed in the request body, or the webhook body might simply contain a notification message indicating that orders are ready for you to pull.

For webhooks to be received, a process flow must be deployed and enabled.

About Patchworks webhook URLs

URLs

Patchworks webhook URLs are generated in the form:

http://webhooks.wearepatchworks.com/api/v1/{{company}}/{webhook_id}

For example:

http://webhooks.wearepatchworks.com/api/v1/docsdemo/01h5mjh0akmca5ajm5wret3rm0?patchworks_signature=akhmm3jw5akh5thrma1234abcdef5armm2050j5rt0e35m1hawj1ec1 

The {{webhook_id}} is a Patchworks signature which is 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.

Default response

The default response for a successful webhook trigger is a status code of 200, with the following body:

{
  "message": "Flow initialised."
}

If required, you can customise this response.

GET or POST?

You can send both GET and POST requests to a webhook. The table below summarises support for passing in data with requests:

Data mechanism	POST	GET
Body content	supported	supported
URL parameters	supported	supported

If a request includes both body content and URL parameters, the body content takes precedence (URL parameters are ignored).

Adding a trigger webhook

Follow the steps below to add a new webhook trigger.

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

Step 2 Click the add new webhook button:

...a unique Patchworks webhook URL is generated:

Step 3 Copy this URL and paste it into your third-party application.

The documentation for your third-party application should guide you through any required webhook setup.

Step 4 If you want to customise the response for your webhook, click the edit icon associated with the URL and make the required changes. For more information please see Customising your webhook response.

Step 5 Build the rest of your process flow to handle incoming data from your defined webhook(s).

Step 6 Ensure that your process flow is deployed and enabled - webhooks will not be received if this isn't done.

Customising your webhook response

If required, you can change the default response for your webhook by selecting the 'edit' icon associated with the URL - for example:

Here, you'll find options to select an alternative status code and specify new body text:

Here you can:

• Use the status code dropdown field to select the required response code.

• Enter the required text in the body field.

• Select the required format for your body content (choose from JSON, XML or Plain text).