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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.