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.
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=0bzmguhjf767m236b9yye14cftmc4fvvsrs0x85kex7c76444m64These elements are summarised below:
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:
Body content
URL parameters
Adding a trigger webhook
Follow the steps below to add a new webhook trigger.
Access trigger shape settings
Click the settings icon associated with the trigger shape in your process flow:
(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:
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:
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.
(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.
Complete process flow development
Build the rest of your process flow as required.
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).
Last updated