UpGuard uses webhooks to notify your other applications when an event happens in your account. This could be when an identity breach or data leak is detected, the score of a watched vendor drops below a threshold, or when a user requests access to your Shared Profile.

Begin using webhooks with your UpGuard integration in five steps:

  1. Provide basic information about the integration
  2. Choose event trigger(s)
  3. Provide a webhook destination
  4. Define the payload structure
  5. Enable/disable integration

What are webhooks?

Webhooks refer to a combination of elements that collectively create a notification and reaction system within a larger integration.

Metaphorically, webhooks are like phone numbers that UpGuard calls to notify you of activity in your UpGuard account. The activity could be a change in a vendor’s score. The webhook endpoint is the person answering the call who takes action based on the information provided to it by UpGuard.

In actuality, the webhook endpoint is just code in your application, which could be written in any programming language. The webhook endpoint has an associated URL (e.g. https://upguard.com/webhook-example). UpGuard’s payloads use Liquid, an open-source template language originally created by Shopify.

1. Provide basic information about the integration

Head over to the Integrations page under Account Settings and then click “New Integration” in the top right corner of your screen. Your screen should now look similar to below. Go ahead and name your integration. In this example, we’ve named ours “UpGuard Integration”.

2. Choose event trigger(s)

You can choose from a range of pre-defined event triggers such as:

  • When a company’s score drops below 600
  • When a vendor’s score drops by 10 in 7 days
  • When a new data leak is published

Once you have decided what triggers you want to employ, click on the associated pill which will slide it to the right, and enable the trigger. In the example below, we have chosen “When my company’s score drops below 600” as our trigger.

Click “Confirm and Next” to continue.

3. Provide a webhook destination

Now that you’ve defined your trigger(s), you’ll need to provide the URL of your webhook, along with any HTTP Header or parameter values required to connect to your webhook. In this example, we’ve chosen to use “https://www.upguard.com/webhook-example”.

4. Define a payload structure

You’ve now named your integration, chosen trigger(s), and provided a destination. It’s time to define your payload by trigger type. For each trigger, we provide a default payload template that will look something like this:

{
"notification": {
"id": {{ notification.id }},
"type": {{ notification.type }},
"description": {{ notification.description }},
"occurredAt": {{ notification.occurredAt }},
"context": {
"LatestScore": "{{ notification.context.LatestScore }}",
"PrevScore": "{{ notification.context.PrevScore }}",
"Threshold": "{{ notification.context.Threshold }}"
}
}
}

We also provide sample notification data so you can see what your payload will look like with real data. The corresponding data for the above payload looks like this:

{
"notification": {
"id": 29,
"type": "CustomerCSTARUnderThreshold",
"description": "The score for 'Example Company' dropped below 600 with a score of 599",
"occurredAt": "2020-06-29T01:14:11.323507851Z",
"context": {
"LatestScore": 599,
"PrevScore": 732,
"Threshold": 600
}
}
}

As is evident in the template for each trigger type, an attribute of the notification data structure can be referenced in a liquid template using the {{ name }} syntax. Attributes can be identified with dot notation with respect to the sample data structure.

For example, {{ notification.description }} refers to the description “The score for 'Example Company' dropped below 600 with a score of 599”. In the same spirit, if you would like to refer to the LatestScore of 599, you would use {{ notification.context.LatestScore }}.

In some situations, you may want to use Liquid’s conditional control structures to adjust the payload template to your liking. Control structures can be added using the {% %} syntax. For example, imagine you have a Slack channel called “vendor-notify” that is used to keep on top of vendor scores and you wanted to use UpGuard to provide automatic updates.

In this situation, you may opt to alter the payload contents based on the Latest Score from the data structure shown above and use the following if/esif/else control structure:

{
"channel": "#vendor-notify",
"username": "cyber risk",
"icon_emoji": ":female-office-worker:",
"attachments": [
{
"text": "{{notification.description}}",
{% if notification.context.LatestScore < 200 %}
"color": "danger"
{% elsif notification.context.LatestScore < 400 %}
"color": "warning"
{% else %}
"color": "good"
{% endif %}
}
]
}

After configuring your payload template, click the “Send test message” button to test whether your webhook is working properly before setting the integration live. We’ll provide your webhook’s response in the box below the payload template.

Once it’s working, click the “Confirm and Next” button.

5. Enable/disable integration

After building and testing your webhook, it’s time to set it live. To do so, click the “Enable this integration” pill and click “Finish”.

Did this answer your question?