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 services. 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 Developers in the main navigation of your Canary Service Panel to view and manage your API keys.

Authentication to the API is performed via HTTPS 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:

ParametersTypeDescription
titlestringA unique identifier for the trigger.
event_typestringThe type of trigger created. At this time, the only event type is trigger, which you indicate with1.
descriptionstringA longer description of the trigger, including additional human-readable details.
algorithmstringThe algorithm used to detect the event for the trigger; choose between the two threshold types.
metricstringThe specific metric tracked by the trigger.
quantastringThe frequency by which you want Canary to check the metric; must be either hour or day.
parametersobjectThe actual threshold values that, when crossed, fire the trigger; you'll only configure parameters if the algorithm is basic_threshold_v1.
statusstringWhether 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.

AttributesTypeDescription
idstringUnique identifier for the event notification.
user_idstringThe Canary user id who created the trigger.
sourcestringThe source of the event (advice, technical, or trigger).
source_idstringThe id of the source trigger for the event.
algorithmstringThe algorithm used to detect the event for the trigger.
shortnamestringThe short name describing the event.
descriptionstringA longer description of the event, including additional human-readable details.
detailsobjectThis file is currently reserved for future releases.
metricsarray of objectsInformation 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.
thresholdsarray of objectsInformation 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.
createddate-typeWhen the data changed enough to trip the trigger and cause the event.

Alerts

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

  • Email - Canary emails one or more specified email addresses each time an event happens.
  • 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:

ParametersTypeDescriptions
activebooleanTrue if the notification is active.
source_idstringid value for the trigger that fires this notification.
web_enabledbooleanTrue if you want to receive web UI notifications when the trigger fires.
mobile_enabledbooleanTrue if you want to receive mobile app notifications when the trigger fires.
emails_enabledbooleanTrue if you want to receive an email notification when the trigger fires.
webhooks_enabledbooleanTrue if you want to sent a notification via a webhook when the trigger fires.
emailsarray of stringsIf emails_enabled is set to true, provide one or more email addresses to which Canary will send notifications.
webhooksarray of stringsIf `webhooks_enabled is set to true, provide a webhook endpoint URL.