Hooks

A hook is a mechanism that enables apps to receive data updates in real-time and that connects two different applications. The Countly Hooks feature will bring together triggers and effects. It is incredibly helpful when you're working with data updates that need to be notified immediately, such as payment transactions and purchasing processes. The Hooks feature allows you to listen to triggers on incoming data and internal actions on Countly, which will then send relevant data to an external URL in real-time or send an email. In other words, Hooks let you transfer data to other services you use when events happen in your Countly account.

How Hooks Works

The Hooks feature allows you to capture events and user data from Countly, or post data to Countly via generated API endpoint. When an event is captured on the Hook, it serializes data about that event and you can choose to send this data by HTTP request or email. It allows creating rules, where each rule would have one trigger, and one or many effects.

Understanding Hooks

Trigger

Every hook requires a trigger. A trigger is the event, tracked data, or internal action that fires the hook mechanism. Triggers are grouped into three categories:

• Tracked Data
• Internal Actions
• API Endpoint
• Scheduled Trigger

Let us delve into these in detail.

Tracked Data

It listens to events defined for the selected application, checks for matching data, and triggers an effect if matching data is found. It i ncludes events created by users (e.g., linkedButton etc.), reserved Countly events (like View, NPS, and Crash), and data like Network trace etc. You can filter the events by event or user properties before firing the hook mechanism .

Internal Actions

API Endpoint

It generates a random ID to use in API endpoint and you can use this URL in some external services, like webhook, by copying it. When you set up this trigger, a unique URL is generated by Countly. You can use this to configure the settings in a third-party application or code to send data to Flow when a particular data update happens.

Scheduled Trigger

Users can select adding a new trigger type, as a recurring trigger. A scheduled trigger can be used for periodically reading data from MongoDB for a specific day. You can run the trigger at a fixed period (for example, every 7 days).

For these hooks, the Hook job will run every hour and check if there are hooks that should be triggered at this specific hour/day/date. This is very similar to Email Reports. The data that will be provided for actions from this trigger will be year, month, day, and hour.

Action

After defining the trigger, the next step is to select the Action. The action can be of three types:

• Send an E-mail
• Make HTTP Request
• Custom Code

Let us delve into these in detail.

Send an E-mail

This action enables sending an internal email with data from the trigger, which can be formatted as a nested list for displaying JSON objects. Users can add multiple email addresses, or deselect addresses by clicking the remove icon (X) after they have been added. The e-mail address format is automatically checked, and if the entered e-mail address doesn’t match with an acceptable e-mail format, a warning message is shown below the input field.

Make HTTP Request

You can simply provide a URL to call and pass the data from the trigger. It allows you to select to call either via GET or POST:

• POST data: This makes a POST request to a URL.
• GET data: This makes a GET request to a URL with query data.

If this action type is selected, a new input field for URL, a dropdown for call method options, an input field (Payload) for Query string (for GET) or request body (for POST) will appear below the Action type dropdown:

• URL copied from a third-party tool is pasted into the URL input field. This field is used for entering URL to send the data to a third-party tool.
• One of the GET or POST calls is selected.
• Payload: Use {{payload_json}} to include the entire trigger data as a JSON object in your request body, or {{payload_string}} to include a stringified JSON in your query string. You can also use individual properties within the trigger data such as {{user}}.

All these fields are mandatory for HTTP Request action.

Custom Code

Users can set up hooks to receive data from some other service such as API call, which comes in a specific format. You need to use custom code to change the format of incoming to match the countly SDK format and, as the next action, select to call countly API endpoint with that data to ingest it. Users can write custom code to appear in the input field. The c ustom code allows users to add code snippets. I t will be wrapped as an async function and run in a JavaScript vm sandbox. The longest execution time is 30 seconds.

Using Hooks

First of all, make sure Hooks is enabled. To do so, in the Sidebar, go to Management > Feature Management and enable the Hooks toggle.

Default View

Go to Management > Hooks . The default View is the main Hooks page.

Here, you will see a table with data on all Hooks that have been set up. The table includes the following information:

• Toggle: The toggle switch indicates whether the Hook has been enabled or disabled.
• Hook Name: The name of the Hook as determined when setting up the Hook.
• Trigger > Effect: Details of the trigger and the action it causes.
• Trigger Count: Number of times the trigger has been initiated.
• Last Triggered: Details of the time the trigger was most recently initiated.
• Created By: Details of the person who created the Hook.

Filtering the Table Results

You can choose the data that the table displays by using the two filters at the top of the table:

1. Type of Hook: Select between All Hooks, Enabled, and Disabled to see all the Hooks that have been set up, only those Hooks that are enabled, and only those Hooks that have been disabled, respectively.
2. Application: Using the dropdown menu next to the Type of Hook buttons, you can choose to see the Hooks on all or any specific applications that you are tracking using Countly.

From this page, you can undertake numerous actions as elucidated below.

Creating a New Hook

To create a new Hook, click on the + New Hook button on the top right corner of the default View. This will open up a new drawer where you will be required to fill in the below details.

• Hook Name: Enter a name for the Hook, keeping it simple, understandable, and short. This field is mandatory and the name input field is limited to the SDK limits .
• Description: Optionally, add a short description to explain to your colleagues why you created this Hook. Avoid using special characters or long descriptions.
• Source App: Select the application on which the Hook would apply. You can use the search bar to browse your apps. You can only select one app for each Hook. Click on Next Step to move on to selecting the trigger.
• Select the trigger type: Select any one trigger from the dropdown menu - Tracked Data, Internal Actions, or API Endpoint. Please see the section titled Understand Hooks above for more details on the trigger types. Depending on the trigger you select, undertake the following steps:
  • For Tracked Data:
    • Select one of the listed data or data from the dropdown
    • Set a filtering rule if it is needed. More than one condition can be added
  • For Internal Actions
    • Select one of the listed triggers from the dropdown
    • According to the selected trigger type, please specify it by using the appeared new dropdown. (e.g., select one cohort from the listed cohorts)
  • For API Endpoint
    • Select one of the listed triggers from the dropdown
    • According to the selected trigger type, please specify it by using the appeared new dropdown. (e.g., select one cohort from the listed cohorts)
  • Setting up a Recurring Trigger
    • Select one of the frequency options:
      • every hour (allows you to select a time zone)
      • every day (allows you to select a time zone)
      • every week (allows you to select the day of the week, hour, and time zone)
      • every month (allows to select the day of the month from 1 to 28, hour, and time zone)
• Select when the trigger is run
• Select an action type from the dropdown - Send e-mail, Make HTTP Request, or Custom code. Please see the section titled Understand Hooks above for more details on the action types. You can add more than one action by clicking the Add Action button.
• Test the Hook: Optionally, you can run a test to check if the Hook is running correctly. To do so, click the Test the Hook button. For more information on how to test a Hook, see the section titled Testing a Hook below.

Once you have filled in the above details, you need to save the Hook. To do so, click the Save button. When your Hook is successfully saved, you will see a success message.

Testing a Hook

You can test your Hook before saving it to ensure that it is correctly set up. Once you have filled in all the mandatory fields in the +New Hook drawer, the Test Hook button is automatically enabled. Click the Test Hook button to begin the test. If your trigger is run or data is sent based on the selected action, success messages are shown for both Trigger and Action setups. These messages also contain details, but in collapsible fields. By default, you will only see the result. To see the details of each, click on the collapsible menu to expand it. If the test is unsuccessful, you will need to go through the above details again and ensure that you have accurately filled in the mandatory fields.

Editing a Hook

To see the details of any Hook, you can click on the Hook in the table on the default View. This will take you to the detailed Hook View, including the below details for each Hook:

• Creation Details: Details of the person who created the Hook and date on which it was set up.
• Trigger Count: Number of times the trigger has been initiated.
• Last Trigger Time: Details of the time the trigger was most recently initiated.
• Trigger > Effect: Details of the trigger and the action it causes.
• Last 10 Failed Triggers: Details of the last ten times that the trigger failed, including recording time, on which step it failed, and error message indicating why it failed.

You can download a copy of the report of the Last 10 Failed Triggers by clicking the download arrow on the top right of the table.

You can edit any Hook by clicking on the three dots on the top right corner of the details View. Then click on Edit to make changes. You can also initiate an edit by clicking on the three dots in the right column of the Hooks table (in the default Hooks View) for the relevant Hook, and then clicking on the Edit button.

To go back to the main Hooks View, click on the Back to Hooks button on the top left corner of the detailed Hook View.

Deleting a Hook

To delete a Hook, go to the main Hooks View and click on the three dots button next to the Hook you want to delete, and select the Delete option. A w arning message is shown: the user can then continue to delete if they accept the process, or choose to cancel the process.

Stopping a Hook

To stop any Hook from being triggered, go to the main Hooks View and click on the toggle button to the left of the Hook Name in the Hooks table.