Skip to main content
Skip table of contents

Setting Up Web Alerts (Webhooks)

Use this guide’s step-by-step instructions for setting up web alerts the Portal.

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:

  1. alerts - The overall alert containing the alertTriggers and alertActions information.

    JSON
    {
    	"division":"<the alert's associated division ID>",
    	"alertTriggers":[{"<below>"}],
    	"alertActions":[{"<below>"}],
    }

  2. alertTriggers - The specific event that initiates the Alert’s configured action.

    JSON
    "alertTriggers":[{
    		"event":"<alert resource>",
    		"resource":"<alert resource #>"
    	}],

  3. alertActions - The notification method, delivery format, and destination for the alert.

    JSON
    "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
"New Alert" Request Body
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",
    }]
}
POST /alerts - "New Alert" Parameters
"New Alert" Request Parameters

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

If a referrer does not allow or create merchant logins, do not use the forLogin parameter.

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
"New alertTriggers" Request Body
JSON
{
    "alert": "merchants",
    "event": "merchant.boarded",
    "resource": "9",
    "name": "Merchant Boarded",
    "description": "Merchant was successfully boarded",
    "inactive":"0",
}
POST /alerts - "New alertTriggers” Parameters
"New alertTriggers" Request Parameters

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
"Multiple New alertTriggers" Request Body
CODE
{
    "division": "t1_div_1a2b3c4d5e6f7g8hi9j10k11",
    "name": "Transaction Funded Webook Test",
    "description": "Testing Funded Txn Update",
    "alertTriggers": [
        {
    	"event": "merchant.boarded",
    	"resource": 9,
    	"name": "merchants",
    	"description": "Merchant was successfully boarded.",
    	}
        {
        "event": "merchant.denied",
    	"resource": 9,
    	"name": "merchants",
    	"description": "Merchant has failed boarding process."
        }
    ],

Alert Resources and Event Triggers

Alert Resources Table

Alert Resource

Resource #

Resource Event Triggers

apiKeys

1

create / update / delete

contacts

2

create / update / delete

customers

3

create / update / delete

alertTriggers

4

create / update / delete

iplists

5

create / update / delete

items

6

 

alerts

7

create / update / delete

logins

8

create / update / delete

merchants

9

merchant.created / merchant.boarding / merchant.boarded / merchant.denied / merchant.failed / merchant.held / create / update / delete

orgs

10

create / update / delete

permissions

12

create

decisions

13

create / update / delete

parameters

14

create / update / delete

sessions

15

create

alertActions

16

create / update / delete

tokens

17

create

txns

18

txn.created / txn.approved / txn.failed / txn.captured / txn.settled / txn.returned / txn.delayed.funding

teamLogins

19

create

credentials

20

create / update / delete

members

21

create / update / delete

accounts

22

create / update / delete

plans

23

create / update / delete

subscriptions

24

subscription.created / subscription.approved / subscription.failed / create

subscriptionTokens

25

create

disbursements

26

create / update / disbursemententries/processed

entries

27

 

fees

28

fee / create / update / delete

funds

29

 

orgEntities

30

create / delete

payouts

31

payout / create / update / delete

feeRules

32

create / update / delete

entityRefs

33

create / update / delete

chargebacks

34

 

decisionRules

35

 

entities

36

create / update / delete

facilitators

37

create / update / delete

partitions

38

 

merchantResults

39

 

mccs

40

create / update / delete

mappings

41

create / update / delete

refunds

42

 

batches

43

batch / create / update

txnResults

44

 

confirmCodes

45

resource.created / create / delete

accountVerifications

46

account / create / delete

disbursementResults

47

reserveEntries

48

create

chargebackMessages

49

create

hosts

50

create / update / delete

txnRefs

53

create

verifications

54

create

verificationResults

55

chargebackMessageResults

56

 

assessments

57

create

entryOrigins

58

adjustments

59

create

txnDatas

60

create

orgFlows

62

create / update / delete

orgFlowActions

63

 create / delete

accountVerificationResults

64

 

disbursementRefs

65

 

reserves

66

create

entityReserves

67

create / update

txnReports

68

 

payoutFlows

69

create / update / delete

vendors

70

create

fundOrigins

71

 

entityRoutes

72

create / update

pendingEntries

73

 

terminal

74

create

terminalRefs

75

create

holds

76

create

holdNotes

77

create

files

78

create / delete

messageThreads

79

create / update

messages

80

 message.created / create / update

bins

81

 

feeModifiers

82

create / update / delete

versions

83

 

chargebackDocuments

84

create / update / delete

divisions

85

create / update

entityReturns

86

create / update / delete

chargebackStatuses

87

 

profitShares

88

create / update / delete

profitShareResults

89

 

aggregations

90

create / update / delete

aggregationResultGroups

91

 

aggregationResults

92

 

auditLogs

93

 

invoiceParameters

94

create / update / delete

invoices

95

invoice.created / invoice.cancelled / invoice.expired / invoice.viewed / invoice.paid / invoice.emailed / create / update / delete

secrets

96

 

watchlists

97

 

watchlistItems

98

 

txnMetadatas

99

 

invoiceResults

100

invoiceResult.failure / create

invoiceItems

101

create / update / delete

invoiceLineItems

102

create / update / delete

profitShareRules

103

 create / delete

configurations

104

create / update / delete

currencyRates

105

 

terminalTxns

106

terminalTxn.created / terminalTxn.approved / terminalTxn.failed

terminalTxnDatas

107

 create

terminalTxnRefs

108

 create

terminalTxnResults

109

 

configurationStages

110

create / update / delete

disbursementEntries

111

create / update / delete

decisionActions

112

create / delete

notes

113

create / update / delete

noteDocuments

114

create / update / delete

paymentUpdates

115

create / update / delete

noteDocumentRefs

116

create / update / delete

paymentUpdateGroups

117

create / update / delete

authTokens

118

create / update / delete

reportResults

119

create

reports

120

create

reportItems

121

create / delete 

entityDebts

122

create

billings

123

 

billingModifiers

124

 

statements

125

 

statementEntries

126

 

billingEvents

127

 

fundingParameters

128

 

requestTokens

129

 

accountRefs

130

 

settlements

131

 

entityDatas

132

 

terminalTxnMetadatas

133

 

batchRefs

134

 

verificationRefs

135


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
"New alertAction" Request Body
JSON
{
    "alert": "Merchant Boarded",
    "headerName": "",
    "headerValue": "",
    "type": "web",
    "options": "JSON",
    "value": "https://webhook.site/#!/62ee79fc-356c-492e-aeb9-48ca3b6f4kfc",
    "retries": "3",
}

About https://webhook.site/

Webhook.site, provides a unique, random URL and e-mail address.

Learn more about how to generate your custom URL (UUID).

POST /alerts - "New alertAction" Request Parameters
"New alertAction" Request Parameters

Action

Type

Description

Required

Notes

alert

string

The name of the Alert resource that defines this alertAction.

Required

This is the name field from Part 1: alerts.

headerName

string

The request header name for authentication to the endpoint.

Optional

headerValue

string

The request header value for authentication to the endpoint.

Optional

type

string

The medium to use to deliver this Alert.

Required

The default value is web.

The valid values below determine the delivery method for the alert to be sent.

Valid Values:

  • email - email address

  • web - website notification

  • app - mobile app notification

  • sms - SMS message

options

string

When the 'type' field of this resource is set to 'web', this field determines the format that the Alert data should be sent in.

Required

You can specify if the format the web alerts notification should be sent in. JSON or XML format.

Default value is json.

Valid Values:

  • json - JSON file format

  • xml - XML file format

value

string

A value used to deliver the alert.

Optional

This field should be set to an email address if the type is email, an endpoint if the type is web, etc.

Note: It is recommended that you use https://webhook.site as your test URL.

  • Once this site loads, a custom ID will be present in the URL representing the specific browser of the user.

  • POST, GET, PUT / PATCH, and DELETE requests will be logged when this specific URL with the ID is in the "value" field for alertActions

retries

number

The number of times an alert should be resent in case of a failure.

Optional

This fields can only be set for web type alertActions.

Note: Payrix has a default automatic retry of 1 time. Should you decide to add additional retries, you can do that by optionally adding the retries field for the web type alertAction to set the number of times an alert should be resent in case of a failure.

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:

CODE
 "division": "t1_div_5f875c5401bfbf167ed4695",
    "name": "Merchant Boarded",
    "description": "Merchant has been boarded",
    "alertTriggers": [
        {
    	"event": "merchant.boarded",
    	"resource": "9",
    	"name": "mercahnts",
    	"description": "Merchant was boarded successfully."
    	}
    ],
    "alertActions": [
        {
    	"type": "web",
    	"options": "JSON",
    	"value": "https://webhook.site/#!/62ee79fc-356c-492e-aeb9-48ca3b6f4kfc",
    	}
    ]
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.