# Using HMAC-verified webhooks

{% hint style="info" %}
This is preview documentation; HMAC support will be available following our next scheduled release.
{% endhint %}

## Introduction

*HMAC* (*Hash-based Message Authentication Code*) provides a higher level of security than the standard method for webhooks. 

With a standard webhook, Patchworks is told: *Here is some data.* With an HMAC webhook, Patchworks is told: *Here is some data, and here is proof that this data originates from the source and hasn't been changed*.

## How it works

HMAC uses a shared secret key to create a unique cryptographic signature for every individual message. This is achieved in four stages:

<table><thead><tr><th width="213.91796875">Stage</th><th>Summary</th></tr></thead><tbody><tr><td>Preparation</td><td>Patchworks and your third-party system both know a <code>secret key</code>.  </td></tr><tr><td>Signing</td><td>When your third-party system prepares to POST a webhook, it runs the message body through a hashing algorithm (<code>SHA-256</code> or <code>RIPEMD-128</code>), using the <code>secret key</code>. This produces a <code>signature</code>.</td></tr><tr><td>Transmission</td><td>Your third-party system sends the data in the request <code>body</code>, and the <code>signature</code>, in an <code>X-HMAC-HASH</code> header. </td></tr><tr><td>Verification</td><td>When Patchworks receives the webhook, it takes the request body data and its own copy of your secret key and performs the same hashing calculation to verify that signatures match. If the signatures match, Patchworks knows the data is authentic and untampered. If they don't match, Patchworks rejects the request.</td></tr></tbody></table>

## Configuring HMAC-verified webooks

If you are implementing HMAC webhooks, you will have your own (most likely automated) mechanisms to generate secret keys and HMAC signatures for your webhooks.&#x20;

For demonstration purposes, the steps below show how to configure an HMAC webhook in Patchworks, using manual steps to produce the secret key and HMAC signature.

{% stepper %}
{% step %}
**Add a webhook to the trigger shape & copy the URL**

In your process flow, edit the `trigger` shape and [add a webhook as usual](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-webhook/..#adding-a-trigger-webhook), then copy the URL and save it somewhere safe - you'll need this later. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FgZTDc4WuRGIrhdrYvmp0%2Fadd%20hmac%20webhook%201a.png?alt=media&#x26;token=e00e8dfd-ab8c-4d4e-afa9-8d583441cf70" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Access webhook settings**

Click the edit icon associated with your webhook. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Ftrk8zQFEsWEowIdVDcxB%2Fadd%20hmac%20webhook%201.png?alt=media&#x26;token=aca970be-304c-4db6-b0b8-659fa5bd69db" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Select the HMAC algorithm to be used for hashing (`SHA-256` or `RIPEMD-128`):

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FKd1xwjLYEr3mqJM4woh9%2Fadd%20hmac%20webhook%202.png?alt=media&#x26;token=e0e7fbbd-b232-49d9-a0a0-e24ba7061c1c" alt=""><figcaption></figcaption></figure></div>

You'll notice that a `secret key` field is displayed. For example

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fpc5WuqGeMYPz1V2OD31H%2Fadd%20hmac%20webhook%202a.png?alt=media&#x26;token=d9403cb1-45f7-46c0-bfc8-779c8898975b" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Obtain a secret key**

In a real-world use case, you will most likely have your own secret key ready to apply (and your own mechanisms for creating it). For this demonstration, we use a key generator website ([RandomKeyGen](https://randomkeygen.com/)) to generate a secret key. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FUT5Fc44ck0RIsgme6FOO%2Fadd%20hmac%20webhook%203a.png?alt=media&#x26;token=5c141108-b1d4-4f25-b408-6170ccec4062" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Apply the secret key to your trigger shape**

Switch back to your Patchworks `trigger` shape settings and paste your key into the `secret key` field. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fs01yMQpWGkMxyUYrnDbt%2Fadd%20hmac%20webhook%204.png?alt=media&#x26;token=703b1bfa-c3f0-438f-8db0-342fe9be67dc" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Save settings & deploy process flow**

Save trigger shape settings, then [deploy the process flow](https://doc.wearepatchworks.com/product-documentation/process-flows/managing-process-flows/flow-deployment).

{% hint style="info" %}
To test this webhook, we will be sending an API request. To interact with any process flow via the [Patchworks API](https://doc.wearepatchworks.com/product-documentation/developer-hub/patchworks-core-api), the flow must be deployed and enabled.
{% endhint %}
{% endstep %}

{% step %}
**Generate a HMAC signature using the same secret key**

In a real-world use case, you will most likely have your own mechanism for generating an HMAC signature. For this demonstration, we use an HMAC generator website ([FreeFormatter](https://www.freeformatter.com/hmac-generator.html)) to generate one. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FTP6a1sxM2BB81qedWXvC%2Fadd%20hmac%20webhook%205.png?alt=media&#x26;token=69d37562-750d-4831-be59-d666e681956a" alt=""><figcaption></figcaption></figure></div>

Here, we have pasted a sample payload and our secret key, and selected the required HMAC algorithm. This information is used to generate a signature. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F5tSFIC7gipTQyL8befkw%2Fadd%20hmac%20webhook%206.png?alt=media&#x26;token=976fd9e7-b323-4b5c-86a2-b1d288ed6b6b" alt=""><figcaption></figcaption></figure></div>

Copy this signature somewhere safe - you'll need it in the next step.
{% endstep %}

{% step %}
**Send a test request to the webhook URL**

Use your preferred tool to create a new API request, for example, Postman. Create a new POST request to the webhook URL that you copied at the end of [step 1](#configuring-hmac-verified-webooks). For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FwxiYqSyajgjS9Pz9ILic%2Fadd%20hmac%20webhook%207a1.png?alt=media&#x26;token=fe50b751-0148-4d69-8970-5767cf73fc95" alt=""><figcaption></figcaption></figure></div>

Access `headers` for the request, and add a key named `X-HMAC-HASH`. For the value, paste the signature copied at the end of step 7. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FnWXXKFMGoVFVfhh37JTT%2Fadd%20hmac%20webhook%207b.png?alt=media&#x26;token=827a291c-0b6f-4b77-add7-a9012a9464da" alt=""><figcaption></figcaption></figure></div>

Access the request  `body` and enter **the same sample data** that you used to generate the HMAC signature in step 7. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FLVkBp8156Ij8WkxrhXT7%2Fadd%20hmac%20webhook%207c.png?alt=media&#x26;token=0070d3a5-7406-4baa-963e-70d2241c2cc4" alt=""><figcaption></figcaption></figure></div>

When you send this request, a successful outcome will indicate that the associated process flow has been scheduled. For example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fe9IZVKcnFmHel5PCFVBJ%2Fadd%20hmac%20webhook%207d.png?alt=media&#x26;token=7c5bdc1b-8e0b-4810-b985-34a12c3e61e2" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
You can force a failure by altering the request body data - a single character change is sufficient. When the request is sent, Patchworks receives different data and therefore calculates a different signature (causing the request to fail).
{% endhint %}
{% endstep %}
{% endstepper %}