How do i my bot connect to external services? What is a Webhook?

Updated 6 months ago by Matthew Clementson

A webhook is a link between your bot and some other logic you or a third party host outside of the Hu:toma platform. This is useful as it allows you to carry out a far wider variety of actions based on user chat input than we could ever build ourselves within the Hu:toma platform.

For example, you could look up information in a specific resource you control, or make a booking for a service that you manage.

As seen in the Intents section, when an intent is fulfilled during a chat session, the platform will have recognized that the user has asked a specific question, and matched the question with the "entities" needed.

Then, if a webhook is registered, it will be called, passing on what the user asked, the intent name and the entities the user gave.

It will be up to your webhook logic to provide the answer to the user based on this information.

Passing data about your user from the chat window to the webhook

If you host your own chat client in your website or mobile app, you can pass information from the "client" as a variable which is picked up by the webhook.

So a chat API call with the following headers...

X-Hutoma-Var-Timezone PST%2C%20%2D8
          X-Hutoma-Var-Country  USA
          

... would be received in the webhook as:

{ 
            ...
            "clientVariables": {
              "Timezone": "PST, -8",
              "Country": "USA"
            }
          }
          

Note that URL encoding is used in the values passed.

Securing your webhooks from spoofing

If you provide an HTTPS endpoint to your webhook, the webhook request will be signed using HMAC-SHA256 algorithm so that you can be sure that the request came from Hu:toma and not from anyone else.

To secure your webhook calls, they are signed with a secret which is specific to your bot and only available from the Botstudio. See the webhook signing page for more information.

Example webhook code

Example webhook code is available on our public GitHub repository, along with a more detailed description of how to get your webhook working at this page.


How did we do?