Skip to content

define-webhook-auth.md

Latest commit

 

History

History
200 lines (116 loc) · 6.17 KB

define-webhook-auth.md

File metadata and controls

200 lines (116 loc) · 6.17 KB
copyright
years
2019, 2025
lastupdated 2025-06-09
subcollection watson-assistant

{{site.data.keyword.attribute-definition-list}}

Defining the authentication method for pre-message and post-message webhooks

{: #define-webhook-auth}

This document shows the process for configuring authentication for pre-message webhooks and post-message webhooks in {{site.data.keyword.conversationshort}}. It covers the available authentication methods and how to set them up.

Overview

{: #webhook-auth-overview}

Webhooks allow external systems to communicate with {{site.data.keyword.conversationshort}}. Authentication ensures that only authorized sources can trigger webhooks. This documentation describes the process for configuring and managing webhook authentication, which introduces an updated method for authenticating webhooks.

Before you begin

{: #webhook-before-you-begin}

Before you configure the webhook authentication:

  • You must have write permissions in the environment.
  • You must have authentication details of the target server, including token request URLs (if needed) and any secrets, such as a password or token.

Procedure

{: #webhook-procedure}

  1. Go to Home > Environments.

  2. Select Settings Gear icon from either the Draft tab > Draft environment or the Live tab > Live environment.

  3. Select from either Pre-message webhook or Post-message webhook, according to what you want to define.

  4. Scroll down to Webhook setup, and paste the API URL.

  5. Click Edit authentication to open the Authentication set up page.

  6. In the dropdown, choose one of the following options:

  7. Click Save.

No authentication

{: #no-authentication}

This is the default option.

Basic auth

{: #basic-auth}

  1. Enter a username and password.

Bearer auth

{: #bearer-auth}

  1. Enter the bearer token.

API key auth

{: #api-key-auth}

  1. Enter the API key name and API key.

Signed JWT

{: #signed-jwt}

  1. Enter the Secret.
  2. Click the Show password icon View icon to view the secret.

OAuth 2.0

{: #oauth-20}

If you use the Scope string, it must be a space-delimited set of one or more authentication scopes defined by the target server. For example, write, read+write, email-read, and so on. {: note}

  1. In Grant type, choose one of the following options:

  2. Click Save.

Password

{: #password}

  1. Enter the Username of your webhook.

  2. Enter the Password for your webhook service.

  3. Enter the Client ID for your webhook authentication service.

  4. Enter the Client secret to authenticate your webhook.

  5. Enter the Token URL.

  6. Enter the Refresh token URL.

  7. Optional: If your service needs a scope string, enter the Scope string as defined by the target server.

  8. In Client authentication, you must choose one of the following options:

    • Send as Basic Auth header: Authentication credentials will be sent in the HTTP header.
    • Send as Body: Authentication credentials will be sent in the request body.

  9. Enter the Header prefix, for example: Bearer.

Client credentials

{: #client-credentials}

  1. Enter the Client ID for your webhook authentication service.

  2. Enter the Client secret to authenticate your webhook.

  3. Enter the Token URL.

  4. Enter the Refresh token URL.

  5. Optional: If your service needs a scope string, enter the Scope string as defined by the target server.

  6. In Client authentication, you must choose one of the following options:

    • Send as Basic Auth header: Authentication credentials will be sent in the HTTP header.
    • Send as Body: Authentication credentials will be sent in the request body.

  7. Enter the Header prefix, for example: Bearer.

Authorization code

{: #authorization-code}

  1. Enter the Client ID for your webhook authentication service.

  2. Enter the Authorizing server URL.

  3. Enter the Token URL.

  4. Enter the Refresh token URL.

  5. Optional: If your service needs a scope string, enter the Scope string as defined by the target server.

  6. In Client authentication, you must choose one of the following options:

    • Send as Basic Auth header: Authentication credentials will be sent in the HTTP header.
    • Send as Body: Authentication credentials will be sent in the request body.

  7. Enter the Header prefix, for example: Bearer.

  8. Optional: Depending on the target server, copy the Redirect url to your OAuth app's 'Callback URL' field.

  9. Click Grant Access.

  10. Complete the steps on the page that presents by the granting server.

  11. You are redirected back to the Assistant, and the edit modal re-opens.

  12. Enter the Client secret under Client ID now that the field is visible.

Custom

{: #custom}

  1. Enter the Custom grant type name of your webhook.

  2. Enter the Token URL.

  3. Enter the Refresh token URL.

  4. Optional: If your service needs a scope string, enter the Scope string as defined by the target server.

  5. In Client authentication, you must choose one of the following options:

    • Send as Basic Auth header: Authentication credentials will be sent in the HTTP header.
    • Send as Body: Authentication credentials will be sent in the request body.

  6. Enter the Header prefix, for example: Bearer.

If you need to add custom secrets to your application, follow these steps:

  1. Click Add secret +.

  2. Type the Secret name and the Secret value.

  3. Optional: If you want to add more secret names and secret values, click Add secret +.

  4. Click Add parameter +.

  5. Type the Parameter name, and the Parameter value.

  6. Optional: If you want to add more parameter names and parameter values, click Add parameter +.