Go to Blog

Triggers

Suggest Edits

Behind every event in Canary by Pagos is a trigger that defines when a particular metric warrants attention. In other words, you configure a trigger and when your data "trips" that trigger, Canary registers an event and alerts you of the change. You can create triggers that notify you of changes to your full data set or just specific segments of data; for example, a trigger can alert you when your aggregate approval rate decreases below a specific value, or when only your approval rate for French banks drops unexpectedly.

Triggers Page

To view and manage all your existing triggers, click Triggers in the main navigation. By default, the Triggers page displays all of your triggers in a grid of cards; each card identifies the trigger’s name, the metric it monitors, and the trigger status (e.g. Active or Inactive). Narrow down the list of triggers using the filters at the top of the page:

  • Metric - View all triggers that monitor a specific metric
  • Owner - View triggers created by a specific user in your Pagos organization
  • Status - Filter for all Active or Inactive triggers

You can also search for specific triggers using the search bar at the top of your Canary Service Panel. Type a term into the search bar and Canary will automatically list only those triggers whose name contains that term. Click on a search result to view the trigger’s details.

Managing Trigger Details

Click a trigger card on the Triggers page to view that trigger’s details, including the metric it monitors, the threshold value, the evaluation time, and more. A line graph on the trigger details page demonstrates how your trigger’s chosen metric changed over the last week relative to the trigger’s threshold value. Below the graph, you’ll find a list of events created in response to this trigger; click on an event to learn more.

You can take the following actions from this page:

  • Click the trigger’s status to deactivate or activate it
  • Click Edit Trigger to change any of the trigger’s details
  • Click Alerts to configure how Canary will notify you of new events
  • Click Delete Trigger to permanently delete the trigger from your Canary Service Panel

Creating a Trigger

To create a trigger in Canary:

  1. Open the Canary Service Panel, then click Triggers.
  2. Click Create New Trigger.
  3. Enter a Trigger Name and Trigger Description.
  4. Select the Metric you want to monitor from the drop-down menu.
  5. Define the Aggregation Period, or the time interval for which Canary will review the metric and search for an event. The chosen trigger metric and the processors you've connected to your Pagos account determine which period options you can pick from (e.g. Day, Hour, Month, or Week).
  6. Select an Evaluation Time. Your chosen Aggregation Period determines how this field works:
    1. If set to Day, this is the time(s) each day (in the time zone specified in your account settings) when Canary reviews the metric and searches for an event from the last 24 hours.
    2. If set to Hour, you can choose which hour(s) of each day you want Canary to review the metric and search for events.
    3. If set to Week, you can choose which day(s) of the week you want Canary to review the metric and search for events.
    4. If set to Month, you can choose which day(s) of the month you want Canary to review the metric and search for events.
  7. Select the Threshold Type.
  8. The next step depends on your chosen Threshold Type:
    1. For a Simple threshold, set an exact Threshold value and select whether Canary should alert you when your metric crosses Above the threshold or Below the threshold.
    2. For a Relative threshold, set a Lookback Window—the number of days in the time period Canary uses to calculate the historical range (max: 90 days)—and tell Canary if it should alert you when your metric crosses Above where 95% of your historical data sits or Below it.
    3. For a Relative Percentile threshold, set a Lookback Window—the number of days in the time period Canary uses to calculate the middle percentile range—and tell Canary if it should alert you when your metric crosses Above the 85th percentile or Below the 15th percentile.
  9. Narrow down your trigger threshold by applying up to two Filters.
  10. Click Create Trigger.

To receive a notification whenever your new trigger flags an event, set up an alert.

Creating a Trigger Workflow

This workflow demonstrates exactly how to complete these steps in Canary. Click Read more at the top of the workflow window to reveal more context for each step:

Canary Metrics

At this time, you can set up triggers in Canary for the following metrics:

  • Approval Rate - The percentage of transactions processed that were ultimately approved; calculated by dividing by the total number of approved transactions by the total number of attempted transactions within a given time period
  • Approved Count - The total number of approved transactions in a given time period
  • Average Order Value - The average amount of money each customer spends per transaction; calculated by dividing the total revenue received by the total number of orders processed in a given time period
  • Chargeback Count - The total number of disputed transactions in a given time period
  • Chargeback Value - The total value of all disputed transactions in a given time period
  • Chargeback Rate - The percentage of transactions that were ultimately disputed; calculated by dividing the total number of chargebacks by the total number of transactions in a given time period
  • Decline Rate - The percentage of total attempted transactions declined; calculated by dividing the total number of declines by the total number of attempted transactions
  • Declined Transaction Count - The total number of declined transactions in a given time period
  • Declined Transaction Value - The total value of the declined transactions in a given time period
  • Fee Value - The total amount of fees accrued in a given time period
  • Refund Rate - The percentage of total transactions refunded in a given time period; calculated by dividing the total number of refunds processed by the total number of transactions
  • Refunded Transaction Count - The total number of refunds processed in a given time period
  • Refunded Transaction Value - The total amount of funds refunded to customers in a given time period
  • Share of Declined Count - The percentage of total declined transactions with a specific decline code; calculated by dividing the number of declined transactions with the given decline code by the total number of declined transactions. Select the decline code using the Decline Code filter.
  • Transaction Count - The total number of transactions processed in a given time period
  • Transaction Count Velocity - The period-over-period change of transaction count
  • Transaction Value - The total value of all transactions processed in a given time period

Threshold Types

Canary has three types of thresholds:

  • Simple – A simple threshold detects when your data exceeds a specific minimum or maximum acceptable value. You can customize the threshold value and specify whether you want Canary to notify you when your data falls above or below that exact value.
  • Relative – A relative threshold detects when your metric deviates from your historical average. Canary calculates a threshold range based on where 95% of your historical data sits in the time period specified by your chosen Lookback Window, and notifies you when your data drops above or below that range.
  • Relative Percentile – A relative percentile threshold detects when your metric deviates from the historical disbursement of the middle range of your data. To calculate this middle range, Canary looks at your historical data from the chosen Lookback Window and identifies the 15th percentile (a value higher than 15% of your data disbursement) and the 85th percentile (a value higher than 85% of your data disbursement). Any time your data drops above or below that middle range—depending on the the trigger configuration—Canary will alert you.

Choosing a Threshold Type

How you choose a threshold type depends on how you and your organization think about your data. The simple threshold is a good option if you already know what good performance looks like and you've established specific KPIs for your business. Similarly, if you have a hypothesis about what data values are “normal” for your business, you can use simple thresholds to track and test that theory.

Relative thresholds are great if you don’t want a noisy trigger from Canary; with a relative threshold, you’ll only receive Canary alerts about 5% of the time. They're also helpful when you don't yet know what "normal" looks like in your data. In due time, a relative threshold will identify what data values to expect and what can be considered out of the ordinary (and worth investigating).

Relative Percentile thresholds help you intuitively spot outliers in your data set. The 15th and 85th percentiles Canary identifies when calculating the middle range of your data are actual data points from the Lookback Window for the given metric. This means outliers don’t have to be drastically outside of the average to trip your trigger—they just have to be higher than 85% of your data or lower than 15%. The higher sensitivity of a Relative Percentile threshold means you’ll receive more notifications than a relative trigger, but you’ll never miss a deviation away from the typical range.

Trigger Filters

When you configure a trigger in Canary, you have the option of adding Filters. Filters tell Canary what specific segments of your transaction data to monitor.

To apply filters to a trigger:

  1. When creating a new trigger or editing an existing trigger, scroll to the bottom and click +Add Filter.
  2. Select a filter option from the drop-down menu.
  3. Click the checkbox beside the parameter(s) you want to filter your data by. Learn more about the implications of selecting more than one parameter in the section below.

    1. 📘

      Note

      Depending on your configuration, you may see a text box instead of a list of parameters. In this case, enter the individual parameter values you want to filter your data by, hitting enter betwen each value. For a full list of the filter parameter values, refer to the relevant filter in your Peacock account.

  4. Click Apply Filters.
  5. To add a second filter, click More Filters, then repeat the steps to select a filter option and the desired parameters. At this time, you can only apply up to two filters to a Canary trigger.

Filter Options

You can apply up to two of the following filter options to a Canary trigger:

Filtering Triggers by More Than One Parameter

When you apply a Filter to a trigger and select more than one parameter available for the chosen filter option, Canary effectively creates a different trigger for each segment of your transaction data associated with those parameters. For example, imagine you created a simple threshold trigger to alert you if your approval rate drops below 95% and you applied the Card Brand filter with both the Visa and Mastercard parameters selected; you’d then receive a separate alert when your Visa card approval rate dropped below 95% as you would when the same happens to your Mastercard approval rate.

For relative threshold triggers, Canary calculates a different threshold range for every parameter variable in the chosen filter option. For example, if your company processes transactions in three currencies (e.g. USD, CAD, and EUR), and you configure a relative threshold trigger for Transaction Count that’s filtered by Currency, with all three parameters checked, Canary will establish a threshold range for USD, CAD, and EUR transactions separately. You'll then receive an alert every time your USD transaction count drops below the expected range for transactions made in USD; the same is true for CAD and EUR transactions.

🚧

Notes

  • A single trigger can monitor up to 100 segments of payments data
  • With the BIN, Currency, Issuing Bank, Soft Descriptor, and Issuing Country filters, you can only select up to 12 parameters for a trigger.

Trigger Filters Example

If you wanted to create a trigger that monitors authorization rates for only recurring transactions made with Visa cards, you could set the following parameters when configuring your new trigger:

  • Metric: Authorization Rate
  • Filter 1: Stored Credential
    • Selected filter parameter: recurring
  • Filter 2: Card Brand
    • Selected filter parameter: Visa

Updated 3 days ago

What’s Next