gRPC API specifications

The Custom Business Logic Webhook Service allows webhooks to customize the flow for each event in a call session. Customizations include scheduling new operations, such as biometric operations, disabling nodes in the built-in flow, or setting the webhook’s own session variables.

The following snippet is an example of CustomLogicWebhookService:

/*-
    * #%L
    * business-logic-layer
    * %%
    * Copyright (C) 2021 - 2026 Nuance Communications Inc. All Rights Reserved.
    * %%
    * The copyright to the computer programs herein is the property of
    * Nuance Communications Inc. The programs may be used and/or copied
    * only with the written permission from Nuance Communications Inc.
    * or in accordance with the terms and conditions stipulated in the
    * agreement/contract under which the programs have been supplied.
    * #L%
    */

syntax = "proto3";

package nuance.biosec.v1;

option java_package = "com.nuance.rpc.biosec.v1.bll.webhook";
option java_multiple_files = true;

service CustomBusinessLogic {
    // Invoked when an event is raised.
    rpc OnEvent (Event) returns (CustomLogicResponse);
}

message Event {
    map<string, string> session_variables = 1; // Session variables including the session ID, the event type, all event results collected up to this point, the current configuration, and the built-in flow's state information.
}

message CustomLogicResponse {
    // Required. "200" if OK, anything else if there was an error.
    int32 result_code = 1;
    // Reserved for future use.
    string result_message = 2;
    // List of operations to schedule.
    repeated OperationAction actions_to_perform = 3;
    // Store or update a session variable. Updates are applied in the given order.
    repeated SetSessionVariableAction session_variable_updates = 4;
    // Update the built-in flow's node overrides. Updates are applied in the given order.
    repeated NodeOverrideAction nodes_to_override = 5;
    // Event filter that the system will use for the rest of the session.
    EventFilterAction event_filter = 6;
}

message OperationAction {
    // Required. The action to execute.
    string action = 1;
    // Required. The parameters.
    map<string, string> parameters = 2;
}

message SetSessionVariableAction {
    // Required. The session variable key.
    string key = 1;
    // Required. The session variable value.
    string value = 2;
}

message NodeOverrideAction {
    // Required. The list of node names to disable or enable.
    repeated string node_names = 1;
	// When set to false, the nodes mentioned in node_names are disabled for the rest of the session. When set to true, the listed node names are enabled again.
    bool enable = 2;
}

message EventFilterAction {
    repeated string keys_to_ignore = 1;
    map<string, string> values_to_ignore = 2;
    repeated string events_to_ignore = 3;
}

Input message

Input message that defines parameters for OnEvent and contains session variables for the current session.

Output message

Output message that defines parameters returned by OnEvent. Every event message should have a CustomLogicResponse message, even when the it is empty. For example, when the result_code is 200.

Nodes overridden

Update the list of nodes to override in the built-in flow. The disabled nodes, identified by name, are not executed for the rest of the session unless they are enabled again. By default, all built-in flow nodes are enabled.

Event filters

Event filters that are used for the rest of the session. Only events that pass all the filters are sent. By default, new sessions have no filters defined so all events are sent. The EventFilterAction includes the following parameters:

  • keys_to_ignore - Before sending an event, a delta of the session variables between the previous event and the current one is computed.This delta is the list of keys that have been added since the previous event, or whose value has been modified. If all keys of the delta are in keys_to_ignore, the event is filtered and not sent to the webhook. If any of the filter keys ends with an asterisk (*), it matches all those keys in the delta whose name start with that prefix. The special value, that is *, effectively disables the webhook for the rest of the session.

  • values_to_ignore - Not currently supported.

  • events_to_ignore - Ignore values of state.currentEvent. This has higher priority than keys_to_ignore. This means that matching state.currentEvent values ignores the entire event, regardless of the contents of other session variables. If an event filter name ends with an asterisk (*), then it matches all those events whose name start with that prefix. The special value, that is asterisk, effectively disables the webhook for the rest of the session.