Webhook for Data Alerts

Introduction

Webhook for Data Alerts lets Holistics send an HTTP POST request when a report or dashboard widget matches your alert conditions. This is useful when the alert should trigger an action in another system, such as adding customers to a CRM segment, starting a marketing automation journey, creating a support ticket, or calling an internal API.

For example, you can build a report of members who have not visited in 90 days, then use a webhook alert to send those matched members to a re-engagement workflow as soon as Holistics detects them.

How to set up

To use Webhook, set up Webhook as the destination for your Data Alert.

Webhook Endpoint (required): Enter your webhook URL. The URL must use HTTPS. Holistics will send a POST request to this URL when your data matches the alert conditions.

Payload

The webhook payload includes the alert metadata, the conditions that were matched, and the records that matched those conditions. Your downstream system can use these fields to decide what workflow to trigger.

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 a Catch Raw Hook event

Step 2: Create a JS code step

First, you retrieve the IP from headers__http_x_real_ip in the webhook HTTP request from the 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.