> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-webhook.md).

# 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](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape.md), a[ Patchworks webhook URL with built-in authentication](#about-patchworks-webhook-urls) 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. 

{% hint style="warning" %}
For webhooks to be received, a process flow must be [deployed](/product-documentation/process-flows/building-process-flows/process-flow-versioning.md#deploying-a-draft-or-inactive-version) and [enabled](/product-documentation/process-flows/managing-process-flows/enabling-and-disabling-a-process-flow/enabling-and-disabling-a-process-flow-without-virtual-enviroments.md).
{% endhint %}

{% hint style="info" %}
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](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-webhook/using-hmac-verified-webhooks.md).
{% endhint %}

## 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:

<div align="left"><figure><img src="/files/IDCwc2uf9FEkjGjExcM8" alt=""><figcaption></figcaption></figure></div>

For example:

{% code overflow="wrap" %}

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

{% endcode %}

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:

{% code lineNumbers="true" %}

```json
{
  "message": "Flow initialised."
}
```

{% endcode %}

If required, you can [customise this response](#customising-your-webhook-response).

## GET or POST?

You can send both GET and POST requests to a webhook.&#x20;

{% hint style="info" %}
If a request includes both `body` content and `URL parameters`, the `body` content takes precedence (`URL parameters` are ignored).
{% endhint %}

## Adding a trigger webhook

Follow the steps below to add a new webhook trigger.

{% stepper %}
{% step %}
**Access trigger shape settings**

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

<div align="left"><figure><img src="/files/Ek7UgW5eoqMZigMcvgV7" alt="" width="367"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**(Optional) Select a virtual environment**

If your webhook needs to initialise a process flow that runs in a [virtual environment](/product-documentation/virtual-environments/about-virtual-environments.md), use the `customise URLs for virtual environment` selector to choose the required environment. For example:

<div align="left"><figure><img src="/files/UrDE7mYSJdHSlgNLadhv" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
If you don't use [virtual environments](/product-documentation/virtual-environments/about-virtual-environments.md), ignore this option.
{% endhint %}
{% endstep %}

{% step %}
**Generate a new webook**&#x20;

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

<div align="left"><figure><img src="/files/TkZoQNZsrXjf9vwLArri" alt="" width="375"><figcaption></figcaption></figure></div>

...a [unique Patchworks webhook URL](#about-patchworks-webhook-urls) is generated - for example:

<div align="left"><figure><img src="/files/JxtkRo5FwhC7tgELFDoj" alt="" width="375"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Copy the webhook URL**

Use `copy url` OR `copy ve url` buttons to copy this URL, ready to paste into your third-party application.&#x20;

{% hint style="warning" %}
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.
{% endhint %}
{% endstep %}

{% step %}
**(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](#customising-your-webhook-response).
{% endstep %}

{% step %}
**Complete process flow development**

Build the rest of your process flow as required.&#x20;

{% hint style="info" %}
When you're ready, ensure that your process flow is [deployed](/product-documentation/process-flows/building-process-flows/process-flow-versioning.md#deploying-a-draft-or-inactive-version) and [enabled](/product-documentation/process-flows/managing-process-flows/enabling-and-disabling-a-process-flow/enabling-and-disabling-a-process-flow-without-virtual-enviroments.md). Webhooks will not be received if this isn't done.&#x20;
{% endhint %}
{% endstep %}
{% endstepper %}

## 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:

<div align="left"><figure><img src="/files/WaQMRlkfaLjPfCtRY4qJ" alt="" width="375"><figcaption></figcaption></figure></div>

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

<div align="left"><figure><img src="/files/6ez7SDK2OWGWkgWOm2hO" alt="" width="375"><figcaption></figcaption></figure></div>

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).&#x20;
* Add [HMAC security](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-webhook/using-hmac-verified-webhooks.md).