Logging activity with a webhook

Defining the webhook

You can define one webhook URL to use for logging every incoming message.

The programmatic call to the external service must meet these requirements:

• The call must be a POST HTTP request.

To add the webhook details, complete the following steps:

1. From your assistant, click the icon, and then choose Settings.

2. Click Webhooks > Log webhook.

3. Set the Log webhook switch to Enabled.

   If you cannot enable the webhook, you might need to upgrade your service plan.

4. In the URL field, add the URL for the external application to which you want to send HTTP POST request callouts.

   For example, to write the message to https://www.mycompany.com/my_log_service, you must specify a URL that uses the SSL protocol. In this case, specify a URL that begins with https.

5. In the Secret field, add a token to pass with the request that can be used to authenticate with the external service.

   The secret must be specified as a text string, such as purple unicorn. Maximum length is 1,024 characters. You cannot specify a context variable.

   It is the responsibility of the external service to check for and verify the secret. If the external service does not require a secret, you can leave this field empty.

   It is the responsibility of the external service to check for and verify the secret. If the external service does not require a token, specify any string you want. You cannot leave this field empty.

6. Click the appropriate checkboxes to select Subscribe to conversation logs.

7. In the Headers section, add any headers that you want to pass to the service one at a time by clicking Add header.

   The service automatically sends an Authorization header with a JWT; you do not need to add one. If you want to handle authorization yourself, add your own authorization header and it will be used instead.

Your webhook details are saved automatically.

Removing the webhook

If you decide you do not want to log messages programmatically, complete the following steps:

1. From the assistant overview page, click the icon, and then choose Settings.

2. Click Webhooks > Log webhook.

3. Do one of the following things:

   • To change the webhook that you want to call, click Delete webhook to delete the currently specified URL and secret. You can then add a new URL and other details.
   • To stop calling a webhook to log every message and response, click the Log webhook switch to disable the webhook altogether.

Webhook security

To authenticate the webhook request, verify the JSON Web Token (JWT) that is sent with the request. The webhook microservice automatically generates a JWT and sends it in the Authorization header with each webhook call. It is your responsibility to add code to the external service that verifies the JWT.

For example, if you specify purple unicorn in the Secret field, you might add code similar to this:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

Webhook request body

The request body the webhook sends to the external service is a JSON object with the following structure:

{
  "event": {
    "name": "message_logged"
   },
  "payload": {
    ...
  }
}

The payload object contains the event data to be logged. The structure of the payload object depends on the type of event.