Webhooks
Required license: Professional or Enterprise
Tonic 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 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
Required workspace permission: Configure post-job scripts and webhooks
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 most of the webhook configuration, except for the message body.
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.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.
- 4.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.
- 5.Under Trigger Job Types, select the types of jobs that trigger the webhook. You can trigger a webhook after a data generation job or after an upsert job.
- 6.The header list always contains a
Content-Typeheader. The default value isapplication/json. You cannot delete theContent-Typeheader, but you can change the value. - 7.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.
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 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:
- 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 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.
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.
Required workspace permission: Configure post-job scripts and webhooks
To delete a webhook:
- 1.In the Webhooks list, click the delete icon for the webhook.
- 2.On the confirmation dialog, click Delete.
Required workspace permission: Configure post-job scripts and webhooks
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.