Securing webhooks

Ensure your server is only receiving the expected TextMaster requests for security reasons.

Once your server is configured to receive payloads, it'll listen for any payload sent to the endpoint you configured. For security reasons, you probably want to limit requests to those coming from TextMaster. There are a few ways to go about this. For example, you could opt to allow requests from TextMaster's IP address but a far easier method is to set up a secret token and validate the information.

Setting your secret token

You'll need to set up your secret token in two places: on TextMaster when setting up the webhook URL and your server.

To set your token on TextMaster, simply include the token in the callback URL either globally on the user account or on specific resources. Use a random string with high entropy to generate your token. You can use the following ruby command for example:

ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'

You can then include your secret token as an URL parameter of your choice. For example:

curl "https://api.textmaster.com/v1/clients/users/USER_ID" \
     -X PUT \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '
     {
       "user": {
         "callback": {
           "word_count_finished": {
             "url": "https://example.com/payload?token=6f90f415ca54b100c3e9d24fdf2988cbb0815f5d"
           }
         }
       }
     }
     '

Tips: In the future, TextMaster will use your secret token to create a hash signature of each payload. This will allow to validate the payload sent from TextMaster and make sure it has not be tempered.