2. Software Security

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 authenticate requests, encrypt with SHA256 the “timestamp” and “token” concatenated in a single string with no spaces. Then compare this encrypted string with the “signature” we passed in the request. If they match, the request is authenticated. If it doesn’t, then it’s not authenticated.

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    
else      
  raise "CCPATollfree.com did not authenticate"
end

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

You may decide to not allow timestamps older than a few minutes. This is to mitigate potential replay attacks, which are extremely rare when webhooks are used over https. This is not in the example.