Creating webhooks

Learn to build a webhook, choosing the events your webhook will listen for on TextMaster and how to set up a server to receive and manage the webhook payload.

Now that you understand the basics of webhooks, let's go through the process of building out our own webhook-powered integration. In this tutorial, we'll create a webhook defined at the user level that will be responsible for receiving a notification every time word count has been computed on a new document.

Creating a webhook is a two-steps process. You'll first need to set up how you want your webhook to behave through TextMaster: which events it should listen to. After that, you'll set up your server to receive and manage the payload.

The REST API allows you to manage webhooks. You can use it to list configured webhooks and change their configuration. For example, you can modify their payload URL and/or associated events.

Exposing localhost to the internet

For the purposes of this tutorial, we're going to use a local server to receive messages from TextMaster. First of all, we need to expose our local development environment to the internet. We'll use ngrok to do this. ngrok is available, free of charge, for all major operating systems. For more information, see the ngrok download page.

After installing ngrok, you can expose your localhost by running ./ngrok http 4567 on the command line. 4567 is the port number on which our server will listen for messages. You should see a line that looks something like this:

$ Forwarding    http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567

Make a note of the *.ngrok.io URL. We'll use it to set up our webhook later.

Setting up a webhook

You can set up webhooks either globally, on your user account or on a specific resource. In this tutorial, we'll set up a global webhook.

You can use the following cURL query to create/update webhooks set up on your user account.

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": "http://7e9ea9dc.ngrok.io/payload"
           }
         }
       }
     }
     '

You'll need to replace USER_ID with your own user id and ACCESS_TOKEN with a valid OAuth2 access token.

About OAuth Apps

Notice the payload URL is the URL of the server that will receive the webhook POST requests. Since we're developing locally for our tutorial, we've set it to the *.ngrok.io URL, followed by /payload.