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:

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

JSON

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

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

JSON

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

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",
    	}
    ]
}