Overview

A webhook signature is a security mechanism used to verify that an incoming HTTP request actually comes from the expected provider and hasn't been tampered with. It works by using a shared secret key and a hashing algorithm to create a hash of the payload, which is then compared against the signature provided in the request header.

When SimpliFi sends a webhook, each one contains two entries related to signature. X-SimpliFi-Webhook-Timestamp and X-SimpliFi-Webhook-Signature. Both of these are used to verify the authenticity of the webhook.

Signature Key

This is a pre-shared key which SimpliFi will provide to their client. This key will be used to hash and generate the signature.
Note: Key is not automatically rotated. It would only be rotated if the client requests a new key, or if SimpliFi suspects the key has been leaked. Please make sure to keep the key secret and do not store it in plain text.

Timestamp

SimpliFi calculates a timestamp when it is sending the webhook. It is a difference between the current time and midnight, January 1, 1970 UTC.

Signature

The webhook signature is calculated by combining the Timestamp value and Payload, then using HmacSHA256 algorithm the combined value is hashed. This hashed value is then encoded using Base 64.

Verification

To verify the webhook, a signature should be generated and compared with the supplied signature. What you need is:

Signature Key - This is a pre-shared key generated by SimpliFi and shared offline.

JSON Payload - This is the body of the webhook. The format of the content is in JSON, however it is sent as application/text so that it is not automatically converted into a formatted JSON by any processors.
Note: JSON payload should not be altered in anyway to caclulate the signature. Any extra character (or whitespace) will give wrong results.

Timestamp - This is supplied in the header of the webhook. The key is X-SimpliFi-Webhook-Timestamp.

Signature - This is supplied in the header of the webhook. The key is X-SimpliFi-Webhook-Signature.

Following is an example on how to generate a signature from the above:

Webhook Signature

Overview#

Signature Key#

Timestamp#

Signature#

Verification#

Overview

Signature Key

Timestamp

Signature

Verification