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:
| 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. |
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:
| 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. |