---
description: >-
  This is an optional step. For security purposes, you can add a webhook secret
  to limit requests sent to your webhook endpoint to those only coming from
  LoyaltySurf.
---

# Securing Your Webhooks (optional)

## Adding a secret

1. Go to the _Options_ step in the _Campaign Editor_.
2. In the Webhooks integration, click _Show advanced webhook settings_ and enter the secret (it can be any string of text).
3. Publish/save your changes.

<figure><img src="https://3285719719-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTwFF4MDnpq2eL5eyOdtK%2Fuploads%2FdZF2wWkgscWhC4YgHPNZ%2FScreen%20Shot%202023-01-12%20at%203.29.17%20PM.png?alt=media&#x26;token=081d6684-9076-438a-9853-c1614ec9ac8f" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Once your campaign has a webhook secret, a signature`LoyaltySurf-Signature` will be included in the header of all outgoing requests to your webhook endpoint.
{% endhint %}

## Validating payloads

When your secret token has been set, LoyaltySurf uses it to create a hash signature to include in the header of each event notification payload.\
\
The signature hash is passed along with each request in the header as `LoyaltySurf-Signature`. You will need to compute a hash once the payload is received and compare it against the`LoyaltySurf-Signature` value provided by LoyaltySurf within the header. Those steps are outlined below.

{% hint style="info" %}
The`LoyaltySurf-Signature` header contains a timestamp and a signature hash value. The timestamp is prefixed by `ts=`, and the signature value is prefixed by `v=`.
{% endhint %}

### **Step 1: Extract the timestamp and signature from the header**

Split the header using the `,` character as the separator to get a list of elements. Then split each element using the `=` character as the separator to get a key/value pair.\
\
The value for key/prefix `ts` corresponds to the timestamp and the `v` key/prefix corresponds to the signature you will use to compare your generated hash against.

{% hint style="info" %}
NOTE: `ts` is a Unix timestamp in milliseconds
{% endhint %}

### **Step 2: Prepare the signed payload string for comparison**

Achieve this by concatenating:

* The timestamp (as a string). AKA the value of `ts`
* The character `.`
* The actual JSON payload within the request body

### **Step 3: Determine the expected signature**

Compute an _HMAC_ with a `SHA256` hash function. Use the endpoint's signing secret token as the key (which you added in the _Options_ step in the _Campaign Editor_), and use the signed payload string from **Step 2** as the message.

### **Step 4: Compare signatures**

Compare the LoyaltySurf provided signature within the header to the expected signature. If they match then compute the difference between a current timestamp and the received timestamp `ts`. Then decide if the difference is within your tolerance.

{% hint style="info" %}
**Tip:** The timestamp comparison is completely optional but it will help to protect against timing attacks.
{% endhint %}

## View an example

[View an example here](../examples#example-1-webhooks-with-secret)
