Configuration (gRPC)

To use a gRPC webhook, you must set the value of BusinessLogicWebhookType to gRPC. Additional settings must be set in a JSON object in the configuration BusinessLogicWebhookConfig, as detailed below.

The webhook service must run with TLS on port 443 and implement the gRPC service nuance.biosec.v1.CustomBusinessLogic. We may support additional ports in the future.

The configuration in BusinessLogicWebhookConfig must be a properly formatted JSON object.

Sample contents of BusinessLogicWebhookConfig:

{
  "host": "some.hostname",
  "port": 443,
  "timeoutMs": 1000
}

Here is the expected JSON Schema for the gRPC webhook configuration:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["host", "port"],
  "properties": {
    "host": {
      "type": "string"
    },
    "port": {
      "type": "integer"
    },
    "generateJwtHeader": {
      "type": "boolean"
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 100
    },
    "callStartTimeoutMs": {
      "type": "integer",
      "minimum": 100
    },
    "maxAttempts": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "trustedCACerts": {
      "type": "array",
      "items": {
        "type": "string",
        "contentMediaType": "application/x-x509-ca-cert",
        "contentEncoding": "base64"
      }
    },
    "clientCerts": {
      "type": "array",
      "items": {
        "type": "string",
        "contentMediaType": "application/x-x509-ca-cert",
        "contentEncoding": "base64"
      }
    },
    "oauth2": {
      "type": "object",
      "required": ["tokenEndpoint", "scopes"],
      "properties": {
        "tokenEndpoint": {
          "type": "string",
          "format": "uri"
        },
        "refreshEndpoint": {
          "type": "string",
          "format": "uri"
        },
        "clientId": {
          "type": "string"
        },
        "clientSecret": {
          "type": "string"
        },
        "scopes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        },
        "clientAuthType": {
          "type": "string",
          "default": "basic",
          "enum": ["basic", "post", "jwt", "jwtValue"]
        },
        "customParams": {
          "type": "object",
          "additionalProperties": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "minItems": 1,
                "items": {
                  "type": "string"
                }
              }
            ]
          }
        },
        "jwtValue": {
          "type": "string"
        },
        "jwt": {
          "type": "object",
          "required": ["issuer", "audience", "subject", "key", "algorithm", "expirationMs"],
          "properties": {
            "type": {
              "type": "string",
              "examples": ["JWT"]
            },
            "algorithm": {
              "type": "string",
              "enum": ["RS256"]
            },
            "audience": {
              "type": "string"
            },
            "issuer": {
              "type": "string"
            },
            "subject": {
              "type": "string"
            },
            "keyId": {
              "type": "string"
            },
            "jwtTokenId": {
              "type": "string"
            },
            "expirationMs": {
              "type": "integer",
              "minimum": 1
            },
            "key": {
              "type": "string",
              "contentMediaType": "application/pkcs8",
              "contentEncoding": "base64"
            },
            "certificates": {
              "type": "array",
              "items": {
                "type": "string",
                "contentMediaType": "application/x-x509-ca-cert",
                "contentEncoding": "base64"
              }
            },
            "other": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

The following is the description of each JSON property:

  • host: Required. The hostname of the webhook. Gatekeeper must be able to resolve this hostname and connect to its address.
  • port: Required. Currently, only port 443 is supported.
  • generateJwtHeader: If true, adds the x-jwt header to each request. See JWT Header for more information.
  • timeoutMs: Maximum amount of time, in milliseconds, during which the webhook must respond to a call. By default the maximal timeout is 5 seconds. Any value greater than 5000 is interpreted as 5000.
  • callStartTimeoutMs: Maximum amount of time, in milliseconds, during which the webhook must respond to the CALL_START_EVENT event. Since this is often the first event of a call, the webhook can take more time initializing and caching resources needed for the rest of the session. The call start timeouts are limited to 5 seconds. Any value greater than 5000 is interpreted as 5000.
  • trustedCACerts: A list of DER-encoded x.509 certificates in base64 form. Certificates are typical “crt” files without the “-----BEGIN CERTIFICATE-----” header, without the “-----END CERTIFICATE-----” footer, and all whitespace and newline characters removed. If this is a non-empty array, then the webhook client refuses to connect to the host unless its TLS certificate matches one in this list or was signed by one of the certificates in this list (a Certificate Authority).
  • clientCerts: A list of DER-encoded x.509 certificates, in base64 form (see Encoding of certificate values). The first certificate in the list matching the current client private key is used as the client certificate to use. See TLS client certificate.
  • maxAttempts: The maximum total number of attempts by Gatekeeper to fetch a successful return from the webhook. By default, the value is 5 maximum total attempts. See Error handling.
  • oauth2: Settings for the OAuth 2.0 client. When set, trustedCACerts and clientCerts are also be applied to the OAuth 2.0 client. See OAuth 2.0 Support.

Some important points:

  • The Nuance firewall blocks all ports excluding 443. Contact Nuance support to run your webhook service on a different port.
  • The certificates in trustedCACerts are validated to ensure that they’re proper X.509 certificates. BusinessLogicWebhookConfig isn’t loaded if any of the certificates is improperly encoded.
  • While the per-request timeout is high, slow responses from the webhook can significantly slow down the responsiveness of the contact center flow.