# Creating webhooks

Now that you understand [the basics of webhooks](/webhooks-and-events/webhooks.md), 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](https://ngrok.com/download).

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.

```shell
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.

{% content-ref url="/pages/qYrz6Sqapsud2BoZSSbt" %}
[About OAuth Apps](/apps/about-oauth-apps.md)
{% endcontent-ref %}

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`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.textmaster.com/webhooks-and-events/webhooks/creating-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.