# Securing Your Webhooks (optional)

## Adding a secret

1. Go to the *Options* step in the *Program 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.

![](/files/-M3vdyAlJ0GLVsKTKcLy)

{% hint style="info" %}
Once your program has a webhook secret, a signature `GrowSurf-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, GrowSurf 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 `GrowSurf-Signature`. You will need to compute a hash once the payload is received and compare it against the `GrowSurf-Signature` value provided by GrowSurf within the header. Those steps are outlined below.

{% hint style="info" %}
The `GrowSurf-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 *Program Editor*), and use the signed payload string from **Step 2** as the message.

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

Compare the GrowSurf 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](/developer-tools/webhooks/examples.md#example-1-webhooks-with-secret)


---

# 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://docs.growsurf.com/developer-tools/webhooks/securing-your-webhooks.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.