# 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](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape), 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](https://doc.wearepatchworks.com/product-documentation/process-flows/process-flow-versioning#deploying-a-draft-or-inactive-version) and [enabled](https://doc.wearepatchworks.com/product-documentation/process-flows/managing-process-flows/enabling-and-disabling-a-process-flow/enabling-and-disabling-a-process-flow-without-virtual-enviroments).
{% 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](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-webhook/using-hmac-verified-webhooks).
{% 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:
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.
{% 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:
{% endstep %}
{% step %}
**(Optional) Select a virtual environment**
If your webhook needs to initialise a process flow that runs in a [virtual environment](https://doc.wearepatchworks.com/product-documentation/virtual-environments/about-virtual-environments), use the `customise URLs for virtual environment` selector to choose the required environment. For example:
{% hint style="info" %}
If you don't use [virtual environments](https://doc.wearepatchworks.com/product-documentation/virtual-environments/about-virtual-environments), ignore this option.
{% endhint %}
{% endstep %}
{% step %}
**Generate a new webook**
Move down to the `webhooks` section and click the `add new webhook` button. For example:
...a [unique Patchworks webhook URL](#about-patchworks-webhook-urls) is generated - for example:
{% 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.
{% 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.
{% hint style="info" %}
When you're ready, ensure that your process flow is [deployed](https://doc.wearepatchworks.com/product-documentation/process-flows/process-flow-versioning#deploying-a-draft-or-inactive-version) and [enabled](https://doc.wearepatchworks.com/product-documentation/process-flows/managing-process-flows/enabling-and-disabling-a-process-flow/enabling-and-disabling-a-process-flow-without-virtual-enviroments). Webhooks will not be received if this isn't done.
{% 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:
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](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-webhook/using-hmac-verified-webhooks).
