2. Software Security

Table of Contents

When it comes to webhook, you must validate that the data comes from us. The signature parameters in our request to your endpoint will contain three fields: a random token, a timestamp (milliseconds since Janaury 1, 1970), and a signature which is a HMAC SHA256 of the timestamp concatenated with the random token encrypted with your API Key found in the Webhooks tab in your dashboard.

In order to decode it, please refer to this ruby on rails example:

token = params['signature']['random_token']
timestamp = params['signature']['timestamp']
signature = params['signature']['signature']  

signed_test_data = OpenSSL::HMAC.hexdigest("SHA256",          ENV['CCPATollFree_WEBHOOK_PRIVATE_API_TOKEN'], "#{timestamp}#{token}")

if signed_test_data == signature
  # the request is accepted    
  raise "CCPATollfree.com did not authenticate"

Follow best procedures to store and access your private API key. In this example, we stored it securely in an environment variable.

Another set of attacks on webhooks are replay attacks. An attacker may find that they can replay the full https encrypted webhook. Please check the timestamp at which it was signed, and you may have add a 5 minute check and not allow those. This is not in the example.

Table of Contents