Webhooks

Required license: Professional or Enterprise

Tonic Structural allows you to set up webhooks to fire HTTP POST requests when a data generation or upsert job completes successfully, fails, or is canceled.

Webhooks are only supported for data generation jobs and for upsert jobs, if upsert is enabled. You cannot trigger a webhook after other jobs such as sensitivity scans.

Webhooks enable Structural to integrate more seamlessly into your workflow. These requests can pass information about the data generation job, and can be used to trigger actions in other systems.

One common use of the Structural webhooks feature is to post a message to a Slack channel.

Child workspaces never inherit the webhooks configuration from their parent workspace. Child workspaces always have their own webhooks.

Confirming the notifications endpoint location

Webhooks require access to the Structural notifications server. The notifications server URL and port are set as the value of the environment setting TONIC_NOTIFICATIONS_URL.

On a Docker deployment, the default value is https://tonic_notifications:7001. For a Kubernetes deployment deployed using Structural's provided Helm chart, the default value is https://tonic-notifications:7001.

If the notifications server on your instance does not match the default value, then you must update the value of TONIC_NOTIFICATIONS_URL.

Required information for a webhook

Before you create a webhook, make sure that you have the required information.

Webhook URL

Each webhook requires a webhook URL. This is the URL that receives the webhook message.

The URL cannot resolve to a private IPv4 range.

The application that you send the webhook to should provide information about how to obtain the URL. For example, for information on how to generate the webhook URL for a Slack notification, go to Sending messages using Incoming Webhooks in the Slack documentation.

Header values

Check whether the webhook requires any header values.

For example, an application might require:

A content-type header. For example, Content-type: application/json
The version of an API to use. This might be needed to send an API call to perform an action based on the job status. For example, Accept: application/vnd.pagerduty+json;version=2
Authorization for a third-party service. For example, Authorization: Bearer <token value>

Message properties

By default, the webhook message contains the workspace identifier and name, the job identifier, and the job status.

You must also determine whether your application requires any other properties.

For example, for a Slack notification webhook, you must provide a text property that contains the text of the Slack notification.

Displaying the list of webhooks

You manage webhooks from the Post-Job Actions view. To display the Post-Job Actions view, either:

On the workspace management view, in the workspace navigation bar, click Post-Job Actions.
On Workspaces view, from the dropdown menu in the Name column, select Post-Job Actions.

On the Post-Job Actions view, the Webhooks list contains the list of webhooks.

For each webhook, the list contains:

A toggle to enable or disable the webhook
The name of the webhook
The job statuses that trigger the webhook
The webhook URL
The user who created the webhook
The date and time when the webhook was most recently updated
Options to edit and delete the webhook

Creating and configuring webhooks

Required workspace permission: Configure post-job scripts and webhooks

Creating a webhook

To create a webhook, in the Webhooks panel, click Create Webhook.

On the webhook configuration dialog, you can set up, preview, and test the webhook.

To save the webhook, click Save. The webhook is added to the Webhooks list.

Configuring a webhook

Configuring the webhook settings and headers

On the Settings & Headers tab, you set most of the webhook configuration, except for the message body.

In the Webhook Name field, provide a name for the webhook.
In the Webhook URL field, provide the URL to send the webhook request to.
By default, a webhook requires SSL certificate validation. To bypass the validation, and trust the server certificate, check Trust the Server Certificate (bypass SSL certificate validation). You can use this option if the server has a trustworthy self-signed certificate.
Under Trigger Events, select the data generation job events that trigger the webhook. The webhook can be triggered when a job succeeds, a job fails, or a job is canceled. To trigger a webhook in response to an event, check the event checkbook. For example, to trigger the webhook when a job is canceled, check the Job Cancelled checkbox.
The header list always contains a Content-Type header. The default value is application/json. You cannot delete the Content-Type header, but you can change the value.
To add custom header values for the webhook request:
1. To add a header row, click Add Header.
2. In the Header Name field for each header, provide the header name.
3. In the Header Value field for each header, provide the header value.
4. To remove a header row, click its delete icon.

Customizing the webhook request body

From the Message Body tab, you can customize the body of the request. The message body is sent as a JSON payload that consists of a set of keys and values.

For each property, the Property Name field contains the key, and the Property Value field contains the value.

By default, the message body contains the following properties. The values are variables that are replaced by the actual values for the triggering event. You can use these variables in the values of your custom properties.

jobId - The identifier of the job. To include the job ID in a custom property value, use the {jobId} variable.
jobStatus - The status of the job. To include the job status in a custom property value, use the {jobStatus} variable.
jobType - The type of job (data generation or upsert). To include the job type in a custom property, use the {jobType} variable.
workspaceId - The identifier of the workspace. To include the workspace ID in a custom property value, use the {workspaceId} variable.
workspaceName - The name of the workspace. To include the workspace name in a custom property value, use the {workspaceName} variable.

You can also add other properties to the message body that are needed for the particular webhook. For example, for a Slack notification webhook, you provide a text property that contains the text of the notification.

To add a property:

Click Add Property.
In the Property Name field, provide the key name.
In the Property Value field, provide the value. You can include the default variables in the value. The following example of a text value for a Slack notification includes the job type, job identifier, workspace name, and job status: {jobType} job {jobId} for workspace {workspaceName} completed with a status of {jobStatus).

To remove a property, click its delete icon.

Previewing the request JSON

The Preview tab contains a preview of the JSON body of the request. In the preview, the variables are replaced by sample values.

To copy the JSON to the clipboard, click Copy to clipboard. You can then, for example, use the copied JSON to test the webhook request in another tool such as Postman.

Testing the webhook

From the webhook configuration dialog, you can send a test request. The test request includes the configured headers and message body. The message body uses sample values for the variables.

To send a test request, click Test Webhook.