Introduction to Webhooks

What is a Webhook?

Webhooks are user-defined rules that allow events in Osano to trigger events in other applications like Slack and Jira by sending a request over the internet.

Webhooks can be used to — for example — send your Data Request Manager a Slack message each time a subject rights request is ready for review or to create an issue in JIRA assigned to your Data Discovery Manager each time a data store fails to sync.

How do I create a new webhook?

Users with the Admin role can create new webhooks and test how they will work by clicking your name at the bottom of the left navigation bar and selecting ‘Webhooks’:

Once on the Webhooks page users can create a prospective webhook by clicking the 'Add Webhook' button in the bottom-right corner of the webhooks table.

The Webhooks Configuration page for a prospective webhook will immediately display allowing users to set up a new webhook:

Required Fields

To save a prospective webhook, users must enter a value in the following fields:

• Name - This is an internal name that allows users to identify the webhook on the Webhooks List page.
• Product - This contains a list of Osano products e.g. DSAR. When a product is selected the Event dropdown will populate with a list of events that have defined for that product. If an Osano product is not listed in the Product dropdown, events have not yet been defined for that product.
• Event - This contains a list of events in Osano that can be used to trigger events in external applications like Slack or Jira.
• Method - This contains a list of HTTP methods that can be used when the webhook is triggered. The following methods are available for selection:
  • POST - This method is typically used to request a create action when the webhook is triggered. For example, a user might want to create an issue in JIRA each time a DSAR request has been email verified for requests related to their marketing organization.
  • PATCH - This method is typically used to request an update action when the webhook is triggered. For example, a user might want to update issues that that had been created in JIRA to replace the issue description each time a DSAR request has been completed to remove certain elements potentially containing PI in the original issue description.
  • PUT - This method is typically used to request an update action when the webhook is triggered, similar to the PATCH method. However, this method typically contains an update that replaces the entirety of the original request whereas the PATCH method typically contains an update with instructions on which part of the original request to alter.
  • DELETE - This method is typically used to request a delete action when the webhook is triggered. For example, a user might want to delete issues that had been created in JIRA each time a DSAR request has been completed to eliminate all traces of PI in JIRA after request fulfillment.
  • GET -  Some applications use this method as a generic trigger whose purpose is similar to one of the examples given above.
• URL - This is the URL address where the webhook message will be sent.

Before configuring a webhook it is best to consult the public API and Webhooks documentation for the external application you are trying to create a webhook for.

Settings

The Settings section includes a name field for allowing internal users to identify the webhook. It also includes an 'Active' toggle allowing users to set whether a webhook is active or inactive. Inactive webhooks will not trigger even when their triggering conditions are met.

App and Event

The App and Event section includes a product dropdown which populates a list of events in the event dropdown which can be used to trigger events in external applications.

This section also contains an Organizations field. Organizations can be added to a webhook as an additional triggering condition for the event specified on the webhook. When an organization is added as an additional triggering condition for an event only events associated with one of the listed organizations will successfully trigger. An organization is associated with events for a product in the following ways: 

• + DSAR - An organization is associated with events for the DSAR product when a DSAR was submitted through a form that has been assigned to that organization.
• DISCO - At present an organization cannot be associated with events for the DISCO product.

For example, the webhook below will only be triggered when a DSAR is email verified that is assigned to the Marketing organization.

Actions

The Actions section contains a method dropdown for selecting the HTTP method to be used when the webhook is triggered (e.g. POST, PATCH, PUT, DELETE, GET) as well a URL field for entering the URL address where the webhook will be sent.

Headers

Headers can be added to a webhook within the Headers section to specify information in the webhook request outside of the information contained in the body of the request. Whether headers are needed and what each header may require will depend on the external application the webhook request is being sent to. Additional headers can be added be clicking the 'Add Header' button below each header row. Headers can be deleted by clicking the trash can icon at the right of each header row.

Content

The content section defines the message that will be sent to the external application when the event in Osano is triggered. To the right of the content section is a list of substitutable variables that can be used to embed information about the triggering event in the message sent to the URL defined on the webhook.

How do I test a configured webhook?

The Test button at the top right of the content section can be clicked to test whether the webhook has been correctly configured. When the test button is clicked the webhook configuration that displays on the pagewill be manually triggered. If the test is a success the webhook will fire and a green success notification will display at the bottom right of the page. If the test is a failure, the webhook will not fire and a red failure notificaiton will display at the bottom right of the page.

For additional information about webhooks, please visit our Developer Docs.