Webhook for Data Alerts

Introduction

Webhook for Data Alert simplifies the process of delivering data alerts, allowing you to relay notifications to third-party applications via SMS, phone calls, and API integration. With this feature, automated alerts are assured, keeping you consistently well-informed.

How to Setup

To use Webhook, you have to setup Webhook’s destination:

Webhook Endpoint (required field): Your webhook URL (must be https). Holistics will send a POST request to this URL when your data matches alert conditions.

Payload

In Holistics’ webhooks, the payload consists of these key details:

• metadata (object)
  • data_alert_id (string)
  • data_alert_title (string)
  • report_title (string)
  • dashboard_url (string)
• matched_conditions (array): Describing triggering conditions. Each item will include:
  • field_info: Details on field usage within conditions, including field path, dataset, and model info.
  • condition: Specifies the current condition with operator, modifier, values, and options.
  • aggregation: Indicates any aggregation applied to this field.
  • transformation: Indicates any transformation applied to this field.
• matched_data: Contains data that matched alert conditions
  • fields (array): Column or field names within matched data, serving as keys in each matched_data.records item.
  • records (array): The matched data are presented as objects, each representing a distinct data row.

{
  "metadata": {
    "data_alert_id": 211,
    "data_alert_title": "Admin user alert",
    "report_title": "Demo Alert",
    "dashboard_url": "https://secure.holistics.io/dashboards/3-demo-alert"
  },
  "matched_conditions": [
    {
      "id": 214,
      "field_path": {
        "field_name": "name",
        "joins_path": null,
        "model_id": 1,
        "data_set_id": null
      },
      "aggregation": null,
      "transformation": null,
      "condition": {
        "operator": "is",
        "modifier": null,
        "values": ["Admin"],
        "options": null
      }
    }
  ],
  "matched_data": {
    "fields": ["Id", "Email"],
    "records": [
      {
        "Id": "4",
        "Email": "[email protected]"
      }
    ]
  }
}

Security

To secure webhook data transmission, make sure to use HTTPS for the destination URL. This encrypts communication and protects sensitive information.

For Holistics event verification, please refer to this documentation for the list of authorized IP addresses. This ensures that only valid requests are processed, preventing potential security risks.

info

For instructions on setting up IP Whitelisting in Make (Integromat) and Zapier, please visit this section.

Holistics-signature (Coming Soon)

To ensure message integrity and security, both the webhook provider and client will perform signature verification:

• For Requests from Holistics:
  • Generate a hash string from the API payload and timestamp
  • Encrypt the hash string using the ‘webhook secret’
• Upon Receipt on Your Server:
  • Create a 'signature' by combining the API's request and your secret.
  • Verify the 'Holistics-Signature' in the request's header against this computed 'signature.' If they match, the alert is confirmed to originate from Holistics, fortifying data security.

FAQs

Do you have any tutorials for setting up with third-party tools?

Currently, we support Zapier and Make (Integromat). Here are some resources to help you get started:

• Webhooks by Zapier
• Make (Integromat)’s webhooks

How to set up IPWhitelist in Zapier and Make (Integromat)?

Zapier

For Zapier, you can use a JavaScript (JS) Code Block:

Step 1: Create a Catch Webhook step with Catch Raw Hook event

Step 2: Create a JS code step

First, you retrieve the IP from headers__http_x_real_ip in webhook HTTP request from Catch Webhook step as inputData

Then, use the following code to check if the webhook provider's IP is whitelisted:

const ip_whitelist = <array_of_your_ips_whitelist>;
const ip = inputData.ip;
const is_whitelisted_ip = ip_whitelist.includes(ip);

output = { accepted_ip: is_whitelisted_ip }

Step 3: Create a Filter step with the condition to continue if the IP is accepted

Make (Integromat)

For Make (Integromat), set up IP Restriction in the Webhook step.

If the IP is restricted, Make Webhook will respond with an access denied error.

What happens if my 'zap' (in Zapier) or 'scenario' (in Integromat) fails? Does Holistics track these failures?

Holistics handles ‘zap’ (Zapier) and ‘scenario’ (Integromat) failures differently:

• Zapier: Zapier returns a success status (200) even if the URL is incorrect. In such cases, Holistics may mark the job as failed and send notifications only in cases of internal or network errors.
• Integromat: Integromat requires the exact URL; otherwise, it responds with a 404 error. If the URL is incorrect, Holistics will still mark the job as failed.

To check for errors specific to your 'zap' or 'scenario', please review the logs within the respective tools.