Webhooks
The webhooks feature requires a Professional or Enterprise license.
Tonic allows you to set up webhooks to fire HTTP POST requests when a data generation job completes successfully, fails, or is canceled.
Webhooks are only supported for data generation jobs. You cannot trigger a webhook after a sensitivity scan.
Webhooks enable Tonic 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 Tonic 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.
Before you create a webhook, make sure that you have the required information.
Each webhook requires a webhook URL. This is the URL that receives the webhook message.
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, see Sending messages using Incoming Webhooks in the Slack documentation.
Check whether the webhook requires any header values.
For example, an application might require:
- A
content-typeheader. 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>
By default, the webhook message contains the workspace identifier and name, the job identifier, and the job status.
You also determine whether your application requires any other properties.
For example, for a Slack notification webhook, you provide a
text property that contains the text of the Slack notification.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:
- 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
Post-Job Actions view
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.
On the Settings & Headers tab, you set the name, URL, triggering events, and custom headers for the webhook.
Settings & Headers tab of the webhook configuration dialog
- 1.In the Webhook Name field, provide a name for the webhook.
- 2.In the Webhook URL field, provide the URL to send the webhook request to.
- 3.Under Trigger Events, select the data generation job events that trigger the webhook. By default, the webhook is triggered when a job succeeds, a job fails, or a job is canceled. To not trigger a webhook in response to an event, uncheck the event checkbook. For example, to not trigger the webhook when a job is canceled, uncheck the Job Cancelled checkbox.
- 4.To configure 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.
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.
Message Body tab of the webhook configuration dialog
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 data generation job. To include the job ID in a custom property value, use the{jobId}variable.jobStatus- The status of the data generation job. To include the job status in a custom property value, use the{jobStatus}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:
- 1.Click Add Property.
- 2.In the Property Name field, provide the key name.
- 3.In the Property Value field, provide the value. You can include the default variables in the value. The following example of a
textvalue for a Slack notification includes the job identifier, workspace identifier, and job status:Data generation job {jobId} for workspace {workspaceId} completed with a status of {jobStatus).
To remove a property, click its delete icon.
The Preview tab contains a preview of the JSON body of the request. In the preview, the variables are replaced by sample values.
Preview tab of the webhook configuration dialog
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.
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.
To edit a webhook:
- 1.In the Webhooks list, click the edit icon for the webhook.
- 2.On the webhook configuration dialog, update the webhook configuration.
- 3.Click Save.
To delete a webhook:
- 1.In the Webhooks list, click the delete icon for the webhook.
- 2.On the confirmation dialog, click Delete.
You use the toggle at the left of each webhook to determine whether the webhook is enabled.
When the toggle is in the on position, the webhook is enabled. It is triggered by the selected generation job statuses.
When the toggle is in the off position, the webhook is not enabled, and is not triggered by the selected generation job statuses.