Trigger shape (webhook)

Introduction

Webhook triggers are used 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

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:

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

Webhook ID

A unique identifier for the webhook (different for every webhook 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.

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.

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

PreviousTrigger shape (schedule)NextTrigger shape (callback)

Last updated