What is a web alert?

A web alert (also known as a “webhook”) is a notification sent from the API to your server that triggers when a set event occurs in your portfolio.

Example:

A new Merchant is onboarded to your portfolio.

The boarding status will by default be set to Not Ready, and a web alert can be created to notify your server when the boarding status changes to (Successfully) Boarded and the Merchant is approved to begin processing payments.

If you’re already familiar with our web alerts setup, click here to skip to the Alert Resources table.

How to create a web alert in the API

Web alerts are created by making the following request to our API: POST /alerts

Individual request bodies must be sent via this request to initially setup each web alerts alert. These POST /alerts requests are separated into three parts:

alerts - The overall alert containing the alertTriggers and alertActions information.
{ "division":"<the alert's associated division ID>", "alertTriggers":[{"<below>"}], "alertActions":[{"<below>"}], }
alertTriggers - The specific event that initiates the Alert’s configured action.
"alertTriggers":[{ "event":"<alert resource>", "resource":"<alert resource #>" }],
alertActions - The notification method, delivery format, and destination for the alert.
"alertActions":[{ "type":"<delivery method>", "options":"<code language format of alert>", "value":"<https://webdestination.com>" }],

Remember to validate your Alert Resource and Events

Be sure to verify all web alert configurations against the Alert Resources and Event Triggers table below to validate that the setup can accurately. The server will accept most configuration requests without error, but won’t produce the expected result if the resource doesn’t match it’s corresponding events.

See each section below to learn how to setup each individual component.

Part 1: alerts

alerts determines which users the web alerts will apply to. Thus, if you are creating a web alerts to notify your server of a boarding status change for any new Merchant you boarded to Payrix, including your Division ID would apply the web alerts to all the users within your portfolio. You can limit which users a web alerts applies to by entering their individual Login ID or by using an Org ID to apply the web alerts only to users included within a Group.

POST /alerts - "New Alert" Request

POST /alerts - "New Alert" Parameters

Parameter		Type	Description	Required	Notes

Parameter	Type	Description	Required	Notes
`login`	string	The Login that owns this resource.	Required
`forlogin`	string	The identifier of the Login associated with this Alert.	Optional
`name`	string	The desired name of the Alert.	Optional	Stored as text string and cannot exceed 100 characters total.
`description`	string	A larger summary of the Alert.
`alertTriggers`	array	contains a small array of object data for the Alert trigger settings.		See Part 2: alertTriggers for setup steps.
`event`	string	The type of event configured to trigger the alert.	Required	Also known as Alert “Triggers” For Valid Values: See the Alert Resources expandable content.
`resource`	number	The number that corresponds to the specific event trigger.		For Valid Values: See the Alert Resources expandable content.
`alertActions`	array	contains a small array of object data for the Alert action settings.		See Part 3: alertActions for setup steps.
`type`	string	The medium to use to deliver this Alert.		For Valid Values: See the Alert Actions expandable content.
`options`		When the 'type' field of this resource is set to 'web', this field determines the format that the Alert data should be sent in.
`value`		A value used to deliver the alert.

Part 2: alertTriggers

alertTriggers determines which resource and event will trigger a web alerts. In the case of a web alerts that notifies your server when a new Merchant's boarding status updates to (Successfully) Boarded the API resource is merchant (resource 9) and the event is merchant.boarded. You can see a more comprehensive guide to the resources and events code references in the expandable content below.

POST /alerts - "New alertTriggers” Request

POST /alerts - "New alertTriggers” Parameters

Parameter	Type	Description	Required	Notes

Parameter	Type	Description	Required	Notes
`alert`	string	The name of the alert resource	Required	See valid `alert` field values at the expandable Alert Resources table below.
`event`	string	The event type that triggers the associated Alert.	Required	See valid `event` field values at the expandable Alert Resources table below.
`resource`	number	The corresponding resource number for the event type.	Required	See valid `resource` field values at the expandable Alert Resources table below.
`name`	string	The custom name of this alertTrigger.	Optional	This field is stored as a text string and must be between 0 and 100 characters long.
`description`	string	The description for the alertTrigger.	Optional
`inactive`	integer	Whether or not this resource is active.	Required	Valid Values: `0` - Active `1` - Inactive

You can also create multiple alertTriggers within the same web alerts.

For example, if you want your server to be notified when a new Merchant's boarding status updates to (Successfully) Boarded and when a new Merchant's boarding status updates to Denied, you can add a second alertTrigger from the merchants resource (resource 9) with merchant.denied as the trigger event.

See the example using the same parameters as above in the expandable content below:

POST /alerts - "Multiple New alertTriggers" Request Body

Alert Resources and Event Triggers

Part 3: alertActions

alertActions represents a particular instance of an Alert that is sent out through one particular channel, for example, SMS, mobile application notification, or email. Each alertAction is associated with an Alert resource.

POST /alerts - "New alertAction" Request

POST /alerts - "New alertAction" Request Parameters

Final Result

Following all the steps above, the next time a merchant is boarded successfully under your merchant, you’ll have a web alerts setup to push to your webhook.site profile. Your full GET /alerts request body should look like this when fully configured and setup complete:

Payrix Resource Center

Setting Up Web Alerts (Webhooks)