Workflow Trigger Reference for Webhook Utility Connector

Workflow Triggers initiate workflows and are used to define the data supplied to a workflow. Supported trigger Data Types for this connector are outlined below.

Basic details are shown in the table below.

Trigger Sources

Event Workflow Trigger

Event triggers allow workflows to be triggered from message events rather than on a schedule. Webhook Utility Connector can be triggered from any third-party system with appropriate authentication details (as outlined below).

• Setup
• Webhook URL Construction
• Authentication
• Payload

Setup

After a project has been created, if webhooks are desired, contact your implementation consultant to enable webhook support for projects.

For each webhook, or each unique set of authentication credentials, a new workflow is required.

For easier readability in third-party systems, when creating a new workflow, omit spaces from the workflow name. This best practice avoids URL-encoded space characters in a webhook URL. For example, set up the workflow as “MyEventWorkflow” instead of “My Event Workflow”. While it’s best practice to omit spaces from webhook workflow names, if they are needed, or if an existing workflow is re-configured, spaces are supported via URL-encoding.

Go to the Workflow Trigger section and define the following:

• Connector: Connector.Integration.Webhook

• Connection Config: (select desired configuration)

• Source: Event Workflow Trigger

• Source Settings

  • ID Path: (leave blank or set the desired value based on event data)

• Raw Message Contents

  • Message Format: Select the expected message format, such as Webhook XML or Webhook JSON. See Message Format Reference for more details.

  • other settings may be left as default

Once settings are configured, *Save the Workflow Trigger. Restart the project engine if it was already started.

Webhook URL Construction

Once webhook support is enabled in a project and a workflow has been configured, that workflow’s webhook URL may be used to trigger the workflow.

The URL will be in the following format: https://{saltbox-host}:8000/PEP/ProjectEngine/{CustomerID}/{ProjectID}/{Version}/webhooks/{WorkflowName}

This requires the following details (provided by your implementation consultant, as mentioned above):

• {saltbox-host} - the Saltbox host (application server or cloud container) that supports the project.

• {CustomerID} - This tenant-specific Customer ID is provided by your implementation consultant, and is prefixed with Cust_, for example Cust_000 or Cust_1

• {ProjectID} - The project ID is provided by your implementation consultant, and is prefixed with Proj_, for example Proj_000 or Proj_1. In the Saltbox workflow settings URL, it’s usually the first number after the word “project” (for example: 123 in the URL: https://integration.prod.saltbox.io/project/123/456/workflow/MyEventWorkflow/workflowsettings)

• {Version} - The Version is provided by your implementation consultant, and is prefixed with Ver_, for example Ver_000 or Ver_1. In the Saltbox workflow settings URL, it’s usually the second number after the word “project” (for example: 456 in the URL: https://integration.prod.saltbox.io/project/123/456/workflow/MyEventWorkflow/workflowsettings)

• {WorkflowName} - The name of the workflow that will be used as a webhook. If spaces are included in the workflow name, these must be URL-encoded.

  For example:

  • Workflow name without spaces: https://my-saltbox-cloud-host.saltbox.io:8000/PEP/ProjectEngine/Cust_1/proj_2/ver_3/webhooks/MyEventWorkflow

  • Workflow name with spaces: https://my-saltbox-cloud-host.saltbox.io:8000/PEP/ProjectEngine/Cust_1/proj_2/ver_3/webhooks/My%20Event%20Workflow

Once the webhook enabled, and the URL is constructed, authentication is required to securely call the webhook from a third-party application.

Authentication

Authentication is set up using Connector Configuration. Typically, a Connector Configuration specifies how Saltbox connects outward to a third-party application. However, in this case, Webhook Utility Connector Configuration is used to define how a third-party application can securely connect into a Saltbox project.

Several authentication methods are supported:

• Basic - Authenticate with a username and password.
• Header - Authenticate using one or more custom headers.
• HMAC Header - Authenticate using an HMAC header.
• No Authentication - Not Recommended for production. This allows a third-party system to send data to Saltbox without authentication.

Basic

For Connection Configurations that support Basic authentication, a third-party system may authenticate using the specified config’s username and password.

Header

Header authentication is generally recommended over Basic authentication (where supported by third-party vendors).

Set up a Connector Configuration as outlined below, then use these details to allow a third-party system to securely trigger event-based workflows in this Saltbox project.

Setup:

• Connection Name: (as desired, e.g. WebHookHeaderConfig)
• Connection Description: (as desired)
• Authentication Type: Header
• Header Name: HTTP-X-SB-SIGNATURE (custom header keys may be configured)
• Header Value: (a randomly generated string)

Usage:

In the third-party application, supply the header details as configured.

For example, in Postman, specify the header key/value pair as defined in the Webhooks Connector Configuration Header Name and Header Value.

HMAC Header

HMAC Header authentication is similar to Header authentication, with additional options. Examples will be provided in a future update.

No Authentication

Not Recommended for production. This allows a third-party system to send data to Saltbox without authentication.

Payload

Payload for a webhook event is defined in the Request Body and must be a supported message format, such as JSON or XML. See Message Format Reference for available options.