Verifying signatures

Response and Request Signing

Terra will - in all requests made to your webhooks, and all responses returned from the service - include a header - terra-signature - which will contain a hash value unique to the request and to your developer ID. This allows you to verify that the events were sent by Terra, not by a third party.

The signature secret (Terra Secret) will be provided to you along with your developer ID when it is created.

The verification process can be performed as following:

Example of signature verification


Step 1: Extract the timestamp and signatures 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 prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature

Step 2: Prepare the msg string

The msg string is created by concatenating:

  • The timestamp (as a string)
  • The character .
  • The actual JSON payload (i.e. the request body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use your dev-id signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.