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 the Evaluation Time(s).
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.
   3. For a Seasonal threshold, select whether Canary should alert you when your metric crosses Above or Below expected measurements for the chosen metric.
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.

📘

Note:

A Canary trigger only registers events starting the day it's configured. If you sent Pagos historical payments data when you set up your data connections, Canary won't flag events in that data.

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; this metric option calculates chargeback rate using Visa’s formula (this month’s chargeback count divided by this month’s transaction count)
• Chargeback Rate (Visa) - The percentage of transactions that were ultimately disputed; this metric option calculates chargeback rate using Visa’s formula (this month’s chargeback count divided by this month’s transaction count)
• Chargeback Rate (Mastercard) - The percentage of transactions that were ultimately disputed; this metric option calculates chargeback rate using Mastercard’s formula (this month’s chargeback count divided by this month’s transaction count)
• 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. This threshold type 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 – A relative percentile threshold detects when your metric deviates outside of the “typical” historical range of your data and helps you to find outliers. To calculate this range, Canary looks at the metric data from the chosen Lookback Window and identifies the 5th percentile (a value higher than 5% of the range of all values) and the 95th percentile (a value higher than 95% of all values). Any time your data drops above or below that 5%–95% middle range—depending on the trigger’s configuration—Canary will alert you.
• Seasonal (Beta) - A seasonal threshold looks at measurements of the chosen metric over the last 90 days and models its periodic patterns and trends. Canary will then alert you when your data moves outside of the expected range given the context of expected seasonality. This threshold type is currently in Beta.

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.