Trigger shape (webhook)

Introduction

Webhooks are real-time triggers for your process flows. Instead of Patchworks checking a third-party system for updates every few minutes, that system 'pings' Patchworks whenever an event occurs, scheduling the associated process flow to run.

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.

Information on this page is based on standard webhooks. HMAC (Hash-based Message Authentication Code) webhooks are also supported; for more information, please refer to Using HMAC-verified webhooks.

About Patchworks webhook URLs

URLs

The structure of a webhook 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 webook:

For example:

https://webhooks.wearepatchworks.com/api/v1/docs_demo/01k44sfgt56vbm266ct5xcmyr8ze5/2?patchworks_signature=0bzmguhjf767m236b9yye14cftmc4fvvsrs0x85kex7c76444m64

These elements are summarised below:

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:

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.

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 webhook 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 webook

Move down to the webhooks section and click the add new webhook button. For example:

...a unique Patchworks webhook URL is generated - for example:

4

Copy the webhook 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 webhook triggers this process flow in the correct virtual environment.

5

(Optional) customise webhook behaviour

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.

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

• Add HMAC security.