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.

Not sure what segments of your data you want to monitor? Try out one of our Suggested Triggers! These pre-configured triggers keep an eye on the payments data we consider vital for any commerce business.

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 to build out your own trigger. (Alternatively, click one of the pre-configured triggers under Suggested Triggers. If you go this route, skip down to the Suggested Triggers section.)
  3. Enter a Trigger Name and Trigger Description.
  4. Select the Metric you want to monitor from the drop-down menu.
  5. Select the Processor you want to monitor data for from the drop-down menu; you can select one or multiple.
  6. 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 processor determine which period options you can pick from (e.g. Day, Hour, Month, or Week).
  7. 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. Note: If you import payments data to Pagos via SFTP, Canary automatically sets this time for you based on when we ingest your data each day.
    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.
  8. Select the Threshold Type.
  9. 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 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 95th percentile or Below the 5th percentile. The Lookback Window can be no longer than 90 days.
  10. Narrow down your trigger threshold by applying up to two Filters.
  11. 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 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 5th percentile (a value higher than 5% of your data disbursement) and the 95th percentile (a value higher than 95% 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 Percentile thresholds help you intuitively spot outliers in your data set. The 5th and 95th 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 95% of your data or lower than 5%. The high sensitivity of a Relative Percentile threshold means 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 additional filters to your trigger, 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 four 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 data stream 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 percentile threshold triggers, Canary calculates a different threshold range for each data stream. For example, if your company processes transactions in three currencies (e.g. USD, CAD, and EUR), and you configure a relative percentile 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 data streams. If your applied filters create too many data streams, Canary will prompt you to simplify your trigger configuration.
  • 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

Suggested Triggers

To get up and running with Canary immediately, you can select a Suggested Trigger from our list of pre-configured trigger options. We create these triggers on your behalf, configuring the trigger metric, threshold type, aggregation period, and more to keep an eye on the data segments we think any commerce business can benefit from monitoring. At this time, the following Suggested Triggers are available by default on all Canary accounts:

  • Monitor File-Based Approval Rate - Track the daily approval rate for each file-based processor (dLocal, Chase, WorldPay-Vantiv, Klarna, Paypal), and flag when it drops below the 40-day historical rate for your business.
  • Monitor Fraud Activity - Track daily fraud decline codes as a percentage of total declines, and flag any increases above what was normal in the last 8 days.
  • Monitor Refund Activity - Track the daily total count of refunds and flag when it's above what was normal in the last 14 days.
  • Monitor Chargeback Activity - Track the daily chargeback rate and flag any increases above what was normal in the last 60 days.
  • Monitor Real-Time Approval Rate - Track the daily approval rate for each real-time processor (Adyen, Braintree, Stripe, Generic), and flag when it drops below the 40-day historical rate for your business.
  • Monitor Processing Error Activity - Track the daily error-related decline rate and flag any increases above what was normal in the last 8 days.

To start using a Suggested Trigger, simply click it on the Triggers page. You can then click Edit Trigger to make edits to the trigger fields, or click Alerts to set up trigger notifications.

Updated 1 day ago

What’s Next