Securing Your Webhooks (optional)

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

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.

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.

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

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.

NOTE: ts is a Unix timestamp in milliseconds

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.

Tip: The timestamp comparison is completely optional but it will help to protect against timing attacks.

View an example

View an example here