Notifications
Notifications webhooks notify you whenever an alertable action occurs on the MX system. The payload will contain the action that triggered the webhook, the channels the user has opted into for that notification, the user's contact information, and an object with additional information that relates to the notification.
Generic Payload Fields
| Field | Data Type | Definition |
|---|---|---|
action | String | The name of the notification that occurred on the MX system. |
enabled_channels | Array | The channels the user has enabled for this notification. Possible values are in_app, email, sms, and push. |
user_email | String | When the user has enabled email notifications, this will contain the email address MX has on file, otherwise it will be empty. |
user_mobile | String | When the user has enabled SMS notifications, this will contain the mobile number MX has on file, otherwise it will be empty. |
Account-Related Notifications
| Field | Data Type | Definition |
|---|---|---|
account_number | String | The partner-provided account number. |
available_balance | Decimal | The balance the account owner has available. |
balance | Decimal | The total balance the account owner has available, including any account minimums. |
client_id | String | The unique partner-defined identifier for the institution the account belongs to. |
created_at | Integer | The date and time at which the account was created. |
currency_code | String | The three-letter ISO 4217 currency code. This value may be empty or null; in rare circumstances, it may be invalid. |
guid | String | The unique identifier for the account. Defined by MX. |
estimated_payment_due_at | Integer | The estimated day and time the payment is due. Defaults to the payment_due_at field if present and set to a future date. Otherwise, MX calculates an estimated date based on the day_payment_is_due field (typically provided by the end user). |
low_balance_threshold | Decimal | When the account is a checking or savings account, the threshold a balance would need to cross to be considered low. |
member_guid | String | The unique identifier for the member associated with this account. Defined by MX. |
minimum_payment | Decimal | When the account is a debt account (such as a credit card), the minimum payment that must be made. |
name | String | The name of the account. |
payment_due_at | Integer | The date at which the minimum payment is due. |
revision | Integer | The revision number for the account. |
updated_at | Integer | The date and time at which the account was updated. |
user_guid | String | The unique identifier for the user the account is attached to. Defined by MX. |
user_id | String | The unique partner-defined identifier for the user. |
Action Types for Account Notifications
| Type | Definition |
|---|---|
ACCOUNT_BALANCE_LOW | The account has fallen below the low_balance_threshold. |
DEBT_PAYMENT_REMINDER | The account has an upcoming debt payment that needs to be made. |
Example Account-Related Notification Request Delivered
_32POST /admin/webhooks_32HTTP/1.1_32content-type: application/json; charset=utf-8_32accept: application/json_32User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2_32(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123_32Host: abc.com_32{_32 "action": "ACCOUNT_BALANCE_LOW",_32 "enabled_channels": ["email","in_app","push","sms"],_32 "user_email": "test@abc.com",_32 "user_mobile": "123-456-7890",_32 "account": {_32 "account_number": "A-1234",_32 "available_balance": 11.34,_32 "balance": 12.34,_32 "client_id": "C-1234",_32 "created_at": 123456890,_32 "currency_code": "USD",_32 "estimated_payment_due_at": "12345678990",_32 "guid": "ACT-0288c67b-aa25-db63-1914-3c22f442cad6",_32 "low_balance_threshold": 100.00,_32 "member_guid": "MBR-37460bb7-6b0f-a960-1256-dd07130443f5",_32 "minimum_payment": 25.00,_32 "name": "Visa Platinum",_32 "payment_due_at": 12345678990,_32 "revision": 12,_32 "updated_at": 123456890,_32 "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",_32 "user_id": "U-1234"_32 }_32}
Budget-Related Notifications
| Field | Data Type | Definition |
|---|---|---|
amount | Decimal | A budget amount set by the user for a category’s transaction total during a month. |
category_guid | String | The unique identifier for the budget category. Defined by MX. |
client_id | String | The unique partner-defined identifier for the institution the account belongs to. |
created_at | Integer | The date and time the budget was created. |
guid | String | The unique identifier for the budget. Defined by MX. |
is_exceeded | Boolean | This indicates whether the budget has been exceeded. |
is_off_track | Boolean | This indicates whether the budget is off-track. |
metadata | String | Additional information a partner can store on the budget. |
name | String | The name of the budget category. |
parent_guid | String | The unique identifier for the parent budget. Defined by MX. |
projected_spending | Decimal | The projected amount of spending for the budget. |
revision | Integer | The revision number for the budget. |
transaction_total | Decimal | The cumulative amount of all transactions under the budget. |
updated_at | Integer | The date and time the budget was updated. |
user_guid | String | The unique identifier for the user the budget is attached to. Defined by MX. |
user_id | String | The unique partner-defined identifier for the user. |
Action Types for Budget Notifications
| Type | Definition |
|---|---|
BUDGET_EXCEEDED | User has spent more than 100% of their budgeted amount. |
BUDGET_OFF_TARGET | User is projected to go over budget this month based on current transactions and an analysis of transaction data over the past 90 days. |
Example Budget-Related Notification Request Delivered
_31POST /admin/webhooks_31HTTP/1.1_31content-type: application/json; charset=utf-8_31accept: application/json_31User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2_31(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123_31Host: abc.com_31{_31 "action": "BUDGET_EXCEEDED",_31 "enabled_channels": ["email","in_app","push","sms"],_31 "user_email": "test@abc.com",_31 "user_mobile": "123-456-7890",_31 "budget": {_31 "amount": 1312.00,_31 "category_guid": "CAT-b709172b-4eb7-318e-3b5d-e0f0500b32ac",_31 "client_id": "C-1234",_31 "created_at": 123456890,_31 "guid": "BGT-0288c67b-aa25-db63-1914-3c22f442cad6",_31 "is_exceeded": true,_31 "is_off_track": true,_31 "metadata": null,_31 "name": "Home",_31 "parent_guid": null,_31 "projected_spending": 1420.24,_31 "revision": 12,_31 "transaction_total": 1420.24,_31 "updated_at": 123456890,_31 "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",_31 "user_id": "U-1234"_31 }_31}
Device-Related Notifications
| Field | Data Type | Definition |
|---|---|---|
client_id | String | The unique partner-defined identifier for the institution the device belongs to. |
client_product_name | String | The display name to use for the sender of the alert. |
created_at | Integer | The date and time the device was created. |
guid | String | The unique identifier for the device. Defined by MX. |
make | String | The manufacturer of the device. |
model | String | The model of the device. |
name | String | The name of the device. |
os_name | String | The operating system the device is running. |
os_version | String | The version of the operating system the device is running. |
updated_at | Integer | The date and time at which the device was updated. |
user_guid | String | The unique identifier for the user the device is attached to. Defined by MX. |
user_id | String | The unique partner-defined identifier for the user. |
Action Types for Device Notifications
| Type | Definition |
|---|---|
DEVICE_CREATED | A mobile device has been added to a user's account. |
DEVICE_DELETED | A mobile device has been removed from a user's account. |
Example Device-Related Notification Request Delivered
_27POST /admin/webhooks_27HTTP/1.1_27content-type: application/json; charset=utf-8_27accept: application/json_27User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2_27(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123_27Host: abc.com_27{_27 "action": "DEVICE_CREATED",_27 "enabled_channels": ["email","in_app","push","sms"],_27 "user_email": "test@abc.com",_27 "user_mobile": "123-456-7890",_27 "device": {_27 "client_id": "C-1234",_27 "client_product_name": "MoneyDesktop",_27 "created_at": 123456890,_27 "guid": "DEV-0288c67b-aa25-db63-1914-3c22f442cad6",_27 "make": "Google",_27 "model": "Pixel XL",_27 "name": "My Pixel",_27 "os_name": "android",_27 "os_version": 12,_27 "updated_at": 123456890,_27 "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",_27 "user_id": "U-1234"_27 }_27}
Offer-Related Notifications
| Field | Data Type | Definition |
|---|---|---|
client_id | String | The unique partner-defined identifier for the institution the offer comes from. |
client_product_name | String | The display name to use for the sender of the alert. |
created_at | Integer | The date and time at which the offer was created. |
offer | String | The text to display to the user as part of the offer. |
updated_at | Integer | The date and time at which the offer was updated. |
user_guid | String | The unique identifier for the user the offer is sent to. Defined by MX. |
user_id | String | The unique partner-defined identifier for the user. |
Action Types for Offer Notifications
| Type | Definition |
|---|---|
OFFER | An offer is to be sent to a user as part of a campaign. |
Example Offer-Related Notification Request Delivered
_22POST /admin/webhooks_22HTTP/1.1_22content-type: application/json; charset=utf-8_22accept: application/json_22User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2_22(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123_22Host: abc.com_22{_22 "action": "OFFER",_22 "enabled_channels": ["email","in_app","push","sms"],_22 "user_email": "test@abc.com",_22 "user_mobile": "123-456-7890",_22 "offer": {_22 "client_id": "C-1234",_22 "client_product_name": "MoneyDesktop",_22 "created_at": 123456890,_22 "offer": "Offer text",_22 "updated_at": 123456890,_22 "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",_22 "user_id": "U-1234"_22 }_22}
Transaction-Related Notifications
| Field | Data Type | Definition |
|---|---|---|
account_guid | String | The unique identifier for the account this transaction is under. Defined by MX. |
account_name | String | The name for the account. |
account_number | String | The partner-provided account number. |
amount | Decimal | The amount the transaction is for. |
category_guid | String | The unique identifier for the transaction category. Defined by MX. |
client_id | String | The unique partner-defined identifier for the institution the transaction is a part of. |
created_at | Integer | The date and time at which the transaction was created. |
currency_code | String | The three-letter ISO 4217 currency code. This value may be empty or null; in rare circumstances, it may be invalid. |
date | Integer | The date the transaction was created. |
description | String | A short description of what the transaction is about. |
guid | String | The unique identifier for the transaction. Defined by MX. |
is_fee | Boolean | This indicates whether the transaction represents a fee. |
is_international | Boolean | This indicates whether the transaction is international. |
is_overdraft_fee | Boolean | This indicates whether the transaction represents an overdraft fee. |
member_guid | String | The unique identifier for the member associated with this transaction. Defined by MX. |
revision | Integer | The revision number for the transaction. |
status | String | The status of the transaction, if known. May be PENDING, POSTED, or empty if not known. |
transaction_threshold | Decimal | The amount that a transaction would have to be greater than to be considered large. |
type | String | The type of transaction, if known. May be DEBIT, CREDIT or empty if not known. |
updated_at | Integer | The date and time at which the transaction was updated. |
user_guid | String | The unique identifier for the user the transaction is attached to. Defined by MX. |
user_id | String | The unique partner-defined identifier for the user. |
Action Types for Transaction Notifications
| Type | Definition |
|---|---|
ACCOUNT_DEPOSIT_LARGE | A large deposit has been detected in an account. |
TRANSACTION_EXPENSE_LARGE | A large expense has been detected in an account. |
TRANSACTION_FEE_CHARGE | An account fee has been charged. |
TRANSACTION_IS_INTERNATIONAL | An international transaction has been detected in an account. |
Example Transaction-Related Notification Request Delivered
_37POST /admin/webhooks_37HTTP/1.1_37content-type: application/json; charset=utf-8_37accept: application/json_37User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2_37(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123_37Host: abc.com_37{_37 "action": "ACCOUNT_DEPOSIT_LARGE",_37 "enabled_channels": ["email","in_app","push","sms"],_37 "user_email": "test@abc.com",_37 "user_mobile": "123-456-7890",_37 "transaction": {_37 "account_guid": "ACT-0288c67b-aa25-db63-1914-3c22f442cad6",_37 "account_name": "My Checking",_37 "account_number": "A-1234",_37 "amount": 1312.00,_37 "category_guid": "CAT-b709172b-4eb7-318e-3b5d-e0f0500b32ac",_37 "client_id": "C-1234",_37 "created_at": 123456890,_37 "currency_code": "USD",_37 "date": 1234567890,_37 "description": "Paycheck deposit from ACME Corp",_37 "guid": "TRN-0288c67b-aa25-db63-1914-3c22f442cad6",_37 "is_fee": false,_37 "is_international": false,_37 "is_overdraft_fee": false,_37 "member_guid": "MBR-37460bb7-6b0f-a960-1256-dd07130443f5",_37 "revision": 2,_37 "status": "POSTED",_37 "transaction_threshold": 500.00,_37 "type": "CREDIT",_37 "updated_at": 123456890,_37 "user_guid": "USR-c8f30aa7-670f-c920-1155-cd06120243e5",_37 "user_id": "U-1234"_37 }_37}
User-Related Notifications
| Field | Data Type | Definition |
|---|---|---|
client_id | String | The unique partner-defined identifier for the institution the transaction is a part of. |
client_product_name | String | The display name to use for the sender of the alert. |
created_at | Integer | The date and time at which the user was created. |
email_verification_url | String | When the notification is of type EMAIL_VERIFICATION, this will be a one-time use URL that is valid for 24 hours. A GET request to this URL verifies the email address. |
first_name | String | The user's first name. |
guid | String | The unique identifier for the user. Defined by MX. |
institution_name | String | The financial institution's display name. |
last_name | String | The user's last name. |
sms_verification_token | String | When the notification is of type SMS_VERIFICATION, this will be a one-time use token that is valid for 10 minutes. The user will need to input this token into the MoneyMap UI in order to validate their phone number for receiving texts. |
updated_at | Integer | The date and time at which the user was updated. |
user_id | String | The unique partner-defined identifier for the user. |
Action Types for User Notifications
| Type | Definition |
|---|---|
EMAIL_VERIFICATION | A new email address has been added that needs to be verified. |
EMAIL_VERIFIED | A new email address has been successfully verified. |
PASSWORD_CHANGED | The user's password has been changed. |
PASSWORD_RESET_TOKEN | A request has been made to change the user's password. |
SMS_VERIFICATION | A new SMS-enabled mobile device has been added that needs to be verified. |
WELCOME_NEW_USER | A new user has logged into their account for the first time. |
Example User-Related Notification Request Delivered
_26POST /admin/webhooks_26HTTP/1.1_26content-type: application/json; charset=utf-8_26accept: application/json_26User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2_26(2015-09-02)) Date: Thu, 14 Apr 2016 04:26:04 GMT Content-Length: 123_26Host: abc.com_26{_26 "action": "EMAIL_VERIFICATION",_26 "enabled_channels": ["email","in_app","push","sms"],_26 "user_email": "test@abc.com",_26 "user_mobile": "123-456-7890",_26 "user": {_26 "client_id": "C-1234",_26 "client_product_name": "MoneyDesktop",_26 "created_at": 123456890,_26 "email_verification_url": "https://widgets.moneydesktop.com/email_verifications/abc123",_26 "first_name": "John",_26 "guid": "USR-0288c67b-aa25-db63-1914-3c22f442cad6",_26 "institution_name": "Epic Bank",_26 "last_name": "Doe",_26 "sms_verification_token": "123456",_26 "updated_at": 123456890,_26 "user_id": "U-1234"_26 }_26}