What is a Signature?

Webhook signatures are provided so that users can verify webhook requests to an endpoint came from Tive and not from another entity. If a webhook has a secret key populated, an x-tive-signature header to the request allowing it to be optionally verified as legitimate request from Tive.

Signature Anatomy

Users can expect Tive webhook signatures follow the following format:

• x-tive-signature:t=<timestamp>,v1=<signature hash>

The signature can be broken down into the two following pieces of information:

timestamp

This is the timestamp for when the request was sent. It is a UTC timestamp in the format of YYYY-MM-DD HH:MM:SSZ

• Example: 2022-10-31 20:56:28Z

signature hash

This is a Base64 encoded HMAC SHA-256 hash of the contents of the timestamp and the payload sent by the webhook.

• Example: ZGm2T2tx1OqPy+tyC8ssHPq0TkVwAYlbA76QEixRsAw=

Putting these pieces of information together, a signature will look like this:

• x-tive-signature: t=2022-10-31 20:56:28Z,v1=ZGm2T2tx1OqPy+tyC8ssHPq0TkVwAYlbA76QEixRsAw=

How are Signature Hashes Created?

The v1 signature hash is a Base64 encoded HMAC SHA-256 hash of the contents of the timestamp and the payload sent by a webhook.

First, the timestamp and payload are concatenated in the following format: <timestamp>.<payload of the request>

• Example: 2022-10-31 20:56:28Z.{\"Property1\": 123,\"Property2\": \"abc\"}

Next, the signature content is hashed using the HMAC SHA-256 hash algorithm with the webhook secret key as the hashing key. The result is base64 encoded and added to the signature along with a timestamp.

• Example: t=2022-10-31 20:56:28Z,v1=ZGm2T2tx1OqPy+tyC8ssHPq0TkVwAYlbA76QEixRsAw=

Signature Verification

Tive provides the option verify signatures via API or manually.

Endpoint Verification

You can verify that a request to your endpoint came from Tive by using our Verify Signature endpoint. If the signature is valid the endpoint will return a 200 OK response. If the signature is invalid you will receive a 400 Bad Request.

Manual Verification

Alternatively, if you wish to verify the signature manually that is also possible. You will need to do the following:

Step 1

Retrieve the secret key from the webhook. This can be done by finding the secretKey field for a webhook via the Retrieve a Webhook or List Webhooks endpoints.

Step 2

Parse the x-tive-signature header to retrieve the timestamp and signature hash. The x-tive-signature can be parsed using the following regex:

• "^t=([0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}Z),v1=(\S+)$"

The regex will return the following groups:

• [0]: entire string
• [1]: timestamp
• [2]: encoded signature

Step 3

Build a string with the timestamp from the x-tive-signature header and the payload received in the request.

The string should be in the format: {timestamp}.{body}

• Example: 2022-10-31 20:56:28Z.{\"Property1\": 123,\"Property2\": \"abc\"}

Step 4

Compute the HMAC SHA256 hash for the string you generated using the secret key for the webhook.

string signature = $"{timestamp}.{body}";
byte[] bytes = Encoding.UTF8.GetBytes(signature);
byte[] keyBytes = Encoding.UTF8.GetBytes(secretKey);

using HMACSHA256 hmac = new HMACSHA256(keyBytes);
hmac.ComputeHash(bytes);

Step 5

Convert the Hash to a base64 string.

Step 6

Compare the base 64 results with the hash from the x-tive-signature header and ensure that they should match.