Canary API Overview

Canary by Pagos accesses your payments data through our aggregated and normalized Pagos Data Platform and notifies you when things change unexpectedly. Our connection guides provide no-code methods for connecting your payment service providers directly.

If we don't have a guide for your processor or you prefer to have full control over the data you send, we can accept data from any source using our Data Ingestion API. This RESTful API expects to receive any of the core objects on our platform, including transactions and customers.

Authenticating

The Pagos platform uses API Keys to authenticate requests to all our services. Click API Keys in the navigation bar of your Canary Service Panel to view and manage your API keys.

Authentication to the API is performed via HTTP headers. Provide your API key in the x-api-key header when submitting payment transaction information. You don't need to provide a password.

Setting Up a Trigger

To get started with Canary, configure triggers in your data. Triggers define when a particular metric warrants attention; whenever your data fires that trigger, Canary creates an event.

You can generate a trigger on POST: /triggers/configuration/

Parameters

Triggers contain the following required body parameters:

Parameters

Type

Description

title

string

A unique identifier for the trigger.

event_type

string

The type of trigger created. At this time, the only event type is trigger, which you indicate with1.

description

string

A longer description of the trigger, including additional human-readable details.

algorithm

string

The algorithm used to detect the event for the trigger; choose between the two threshold types.

metric

string

The specific metric tracked by the trigger.

quanta

string

The frequency by which you want Canary to check the metric; must be either hour or day.

parameters

object

The actual threshold values that, when crossed, fire the trigger; you'll only configure parameters if the algorithm is basic_threshold_v1.

status

string

Whether the trigger is active or disabled.

Events

Canary creates events whenever your payments data changes in a way that fires one of your triggers. You can pull a list of events with a /events GET request. Each of the query parameters on this request are optional; if you don't specify dates, Canary will provide the most recent events triggered in your account.

To locate the details for a specific event, including information about the trigger that fired it, use the /events/details/{id} GET request. You'll need the id string for the event in question.

Event Object

The event object captures all the details and context around an event, including where in the data it occurred and when, the type of event, and additional descriptions.

Attributes

Type

Description

id

string

Unique identifier for the event notification.

user_id

string

The Canary user id who created the trigger.

source

string

The source of the event (advice, technical, or trigger).

source_id

string

The id of the source trigger for the event.

algorithm

string

The algorithm used to detect the event for the trigger.

shortname

string

The short name describing the event.

description

string

A longer description of the event, including additional human-readable details.

details

object

This file is currently reserved for future releases.

metrics

array of objects

Information about the metric(s) being tracked by the trigger. Each metric associated with the trigger will be represented by the metric object.

Metric object attributes:
metric.metric – Which time series or field that is being observed.
metric.value – The numeric threshold value of the metric that is being observed.
metric.currency – The currency, if applicable, of the metric that is being observed.
metric.value_type – The type of data being observed.
metric.score – The score/strength of the event.

thresholds

array of objects

Information about the threshold met, which tripped the trigger.

Threshold object attributes:
threshold.metric - The metric tracked by the trigger.
threshold.threshold - The actual threshold values that was crossed, thus firing the trigger.
threshold.currency - The currency, if applicable, of the threshold metric that is being observed.
threshold.value_type - The type of data being observed.
threshold.threshold_type - The type of trigger.

created

date-type

When the data changed enough to trip the trigger and cause the event.

Notifications

When an event occurs in your data, Canary can notify you in one or more of the following ways:

  • Web - A notification appears in the Canary Service Panel. This is the default notification setting for all events.
  • Email - Canary emails one or more specified email addresses each time an event happens.
  • Mobile - Canary notifies you of an event via the mobile app.
  • Webhooks - Canary sends event information to the provided webhook endpoint URL, making it possible to incorporate real-time notifications into any system that needs information to trigger other workflows or decisions.

You can configure event notification settings on POST: /triggers/configuration/

Parameters

Notifications contain the following required body parameters:

Parameters

Type

Descriptions

active

boolean

True if the notification is active.

source_id

string

id value for the trigger that fires this notification.

web_enabled

boolean

True if you want to receive web UI notifications when the trigger fires.

mobile_enabled

boolean

True if you want to receive mobile app notifications when the trigger fires.

emails_enabled

boolean

True if you want to receive an email notification when the trigger fires.

webhooks_enabled

boolean

True if you want to sent a notification via a webhook when the trigger fires.

emails

array of strings

If emails_enabled is set to true, provide one or more email addresses to which Canary will send notifications.

webhooks

array of strings

If `webhooks_enabled is set to true, provide a webhook endpoint URL.