> For the complete documentation index, see [llms.txt](https://docs.growsurf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growsurf.com/developer-tools/webhooks/securing-your-webhooks.md).

# Securing Your Webhooks (optional)

Add a webhook secret so your endpoint can confirm each request comes from GrowSurf.

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

![](https://2794996218-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-M3vdUfIEVFzEyb52XMp%2F-M3vdyAlJ0GLVsKTKcLy%2FScreen%20Shot%20on%202020-04-02%20at%2011%3A09%3A29.png?alt=media\&token=bef770d4-c6da-4ac0-9435-3ad857bcff61)

{% 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 webhook secret has been set, GrowSurf uses it to create a hash signature to include in the header of each event notification payload.

{% 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.\
\
`ts` is the timestamp. `v` is the signature to compare with your hash.

{% 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 your webhook secret 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-2-webhooks-with-secret)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.growsurf.com/developer-tools/webhooks/securing-your-webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.