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 LoyaltySurf.
Adding a secret
Go to the Options step in the Campaign Editor.
In the Webhooks integration, click Show advanced webhook settings and enter the secret (it can be any string of text).
Publish/save your changes.
Once your campaign has a webhook secret, a signatureLoyaltySurf-Signature
will be included in the header of all outgoing requests to your webhook endpoint.
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 theLoyaltySurf-Signature
value provided by LoyaltySurf within the header. Those steps are outlined below.
TheLoyaltySurf-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.
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.
Tip: The timestamp comparison is completely optional but it will help to protect against timing attacks.
View an example
Last updated