Setting Up Web Alerts (Webhooks)

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. For example, when a new Merchant is added to your portfolio, their onboarding status will initially be set to Not Ready. You can create a web alert to notify your server when this status changes to Boarded, indicating that the Merchant has been approved to start processing payments.

A web alert is made up of three parts:

Alert: The core resource for creating web alert configurations and assigning users to trigger them.
Alert Trigger: The configuration of the event(s) required to activate the alert action.
Alert Action: The alert communication type and delivery settings when the trigger activates.

Alerts

The Alert determines which users' actions will be monitored to initiate the activation and delivery of the web alert. This can be an individual user, team, group, or division if you’d like to include all users within your portfolio. This part of the web alert setup serves as a package containing all the details about the monitored users, event triggers, and delivery actions assigned to this configuration.

Alert Triggers

The Alert Trigger pinpoints the specific resource and event required to activate the Alert Action, ensuring that the web alert is accurately sent to the intended recipient(s). There are five unique types of Alert Triggers, each linked to specific events that can be monitored to facilitate the delivery of alerts.

When setting up a web alert, you have the option to assign multiple Alert Triggers. This feature acts as a catchall for multiple resource and event types, allowing you to streamline your setup process by covering more than one event that may occur.

Alert Actions

The Alert Action determines the delivery method and destination for the web alert. This can be an email, SMS, mobile app notification, or a webhook. Alert Actions also provide the option to specify how many retry attempts can be made in case of delivery failures.

If you choose to use a webhook as the delivery method, you can also choose the alert data language, such as JSON.

Set up Web Alerts

You can easily set up Web Alerts through either the portal or the API, depending on your preference. Please follow the applicable instructions provided below to build your new web alert.

Create a web alert using the portal

Below are the instructions for creating a web alert on the Payrix platform using the portal. Complete all the steps in the following sections:

Access the Web Alerts page

Click Web Alerts, located in the Admin section of the portal.
Click Add Alert to open the Add Alert dialog.

Build the web alert

Give the Web Alert a custom name and description. Then, click Next.

Set Specific User Monitoring

You can use the Advanced Options in the Add Alert dialog to set specific users, groups, or teams. By default, your entire portfolio is monitored for Alert Trigger event activity unless specified.

Provide the endpoint (destination URL) for alerts, such as webhook.site or an in-app mobile service, and configure any necessary headers. You can include multiple endpoints as needed.
Select the Resource (the Payrix platform endpoint) to monitor, and the Event related to that resource that activates the delivery of the web alert. You can also optionally add a custom name a description to each trigger for easy identification.
Click Add to finish creating the web alert.

Result: You have now created a new web alert that will trigger when the events you specified occur under the specific users you’ve designated.

Create a web alert using the API

Below are the instructions for creating a web alert on the Payrix platform using the API. Before you begin, access our API documentation to have information about request parameters readily available:

To create a new web alert using the API, complete all steps in the following sections:

Create a new alert resource

Create a POST /alerts API request. You’ll need to include the alertActions and alertTriggers endpoint request bodies as JSON objects within this request body. Ensure that both are structured correctly to facilitate the proper setup of the alert.

JSON

{
    "login": "t1_log_123abc456def789ghi",
    "forlogin":"t1_log_123abc456def789ghi",
    "name": "Merchant Boarded",
    "description": "Alert when merchant is boarded.",
    "alertTriggers": [
      {
          "event": "merchant.boarded",
          "resource": "9",
      }
    ],
    "alertActions":[{
      "type": "web",
      "options": "JSON"
      "value": "https://webhook.site/#!/62ee79fc-356c-492e-aeb9-48ca3b6f4kfc",
    }]
}

Automatic Re-Send Attempts

Payrix offers a built-in automatic retry mechanism that attempts to resend an alert once by default. To increase the number of retry attempts, add the retries parameter to the alertAction object body, setting its value to greater than 1, allowing you to specify how many times the alert should be re-sent following a failure.

This is only applicable when the type parameter is set to web

Result: When completed you’ll receive a response indicating all the details of your completed alert configuration. See the example response below:

JSON

{
    "alertActions": [
        {
            "id": "t1_ala_123abc456def789ghi",
            "created": "2025-01-15 15:05:19.2072",
            "modified": "2025-01-15 15:05:19.2072",
            "creator": "t1_log_123abc456def789ghi",
            "modifier": "t1_log_123abc456def789ghi",
            "type": "web",
            "options": "JSON",
            "value": "https:\/\/webhook.site\/#!\/12ab34cd-567e-890f-ghi1-23jk4l5m6n7opq",
            "alert": "t1_alt_123abc456def789ghi",
            "retries": null,
            "headerName": null,
            "headerValue": null,
            "maxAttemptsTempDisabled": 0,
            "inactive": 0,
            "frozen": 0
        }
    ],
    "alertTriggers": [
        {
            "id": "t1_alr_123abc456def789ghi",
            "created": "2025-01-15 15:05:19.2154",
            "modified": "2025-01-15 15:05:19.2154",
            "creator": "t1_log_123abc456def789ghi",
            "modifier": "t1_log_123abc456def789ghi",
            "alert": "t1_alt_123abc456def789ghi",
            "event": "merchant.boarded",
            "resource": "9",
            "name": "",
            "description": "",
            "inactive": 0,
            "frozen": 0
        }
    ],
    "id": "t1_alt_123abc456def789ghi",
    "created": "2025-01-15 15:05:19.1976",
    "modified": "2025-01-15 15:05:19.1976",
    "creator": "t1_log_123abc456def789ghi",
    "modifier": "t1_log_123abc456def789ghi",
    "login": "t1_log_123abc456def789ghi",
    "forlogin": "t1_log_123abc456def789ghi",
    "team": null,
    "name": "Merchant Boarded",
    "description": "Alert when merchant is boarded.",
    "inactive": 0,
    "frozen": 0,
    "division": null,
    "partition": null
}