Skip to main content
Members webhooks notify you when a member is created, updated, or deleted in the MX system for any user on that partner’s client. The X-CALLBACK-PAYLOAD header will appear if it was set in the Create Member or Update Member Platform API request that initiated this webhook.
FieldData TypeDefinition
aggregated_atIntegerThe date and time the most recent aggregation process was started. The process automatically starts when a member is created or its credentials are updated, unless the skip_aggregation parameter is used. Connections can also be started via manual aggregations, background aggregations, API endpoints, or when opening an MX widget. It can be a normal aggregation, or a different process such as identification, verification, fetching statements, or fetching an extended transaction history. If a member is deleted and then re-created with the skip_aggregation parameter set to true or if it is re-created within the throttle window (typically three hours), the previous value will be returned.
connection_status_idIntegerIndicates the state of a member’s aggregation, provided as an integer. See member connection statuses for more information on possible values.
connection_status_messageStringA message that can be displayed to the user to help them navigate the connection and aggregation process.
connection_statusStringThis indicates the state of a member’s aggregation, provided as a string. See member connection statuses for more information on possible values.
created_atIntegerThe date and time at which the member was created.
guidStringThe unique identifier for the member. Defined by MX.
idStringThe unique partner-defined identifier for the member.
institution_codeStringThe unique identifier for the institution associated with the member. Defined by MX.
institution_guidStringThe unique identifier for the institution the member belongs to. Defined by MX.
is_being_aggregatedBooleanThis field will be true if the member is being aggregated at the time of the request. Otherwise, this field will be false.
is_managed_by_userBooleanIf the member is managed by the user this field will be true. Otherwise, the member is managed by the MX partner and this field will be false.
is_manualBooleanIf a member was manually created, this field will be true. Otherwise, this field will be false.
is_oauthBooleanThis indicates whether the member uses OAuth to authenticate. Defaults to false.
is_user_createdBooleanThis field is deprecated. Webhook consumers should use is_managed_by_user instead.
metadataStringAdditional information a partner can store on the member.
most_recent_job_guidStringThe unique identifier for the most recent job. Defined by MX.
nameStringName of the given member.
needs_updated_credentialsBooleanInternal field used by MX in some circumstances. When true, MX will not attempt to aggregate the member. It will be set to false automatically when the member’s credentials are updated.
revisionIntegerThe revision number of this member record.
successfully_aggregated_atIntegerThe date and time at which the account was last successfully aggregated.
updated_atIntegerThe date and time at which the member was last updated.
use_casesArrayThe use case associated with the member. Valid values are PFM and/or MONEY_MOVEMENT. To use this field, you must’ve met with MX and have opted in to using this field. For more info, see Member Use Cases.
user_idStringThe unique partner-defined identifier for the user.
Example Payload
JSON
POST /admin/webhooks
HTTP/1.1
content-type: application/json; charset=utf-8
accept: application/json
User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2
(2015-09-02)) Date: Thu, 12 Jul 2017 04:26:04 GMT Content-Length: 231
Host: abc.com

{
  "action": "updated",
  "member": {
    "aggregated_at": 1588007604,
    "connection_status": "CONNECTED",
    "connection_status_id": 6,
    "connection_status_message": "Connected to Gringotts.",
    "created_at": 1558116397,
    "guid": "MBR-8a4bdc76-2b77-46f8-9e30-39f120e15bfe",
    "institution_code": "gringotts",
    "institution_guid": "INS-80230e9b-bfc3-d488-e606-1bf82f862406",
    "id": null,
    "is_being_aggregated": false,
    "is_manual": false,
    "is_managed_by_user": true,
    "is_oauth": false,
    "is_user_created": true,
    "metadata": null,
    "most_recent_job_guid": "JOB-5ce1788a-3f63-44b9-8642-d015b38b41c0",
    "name": "Gringotts",
    "needs_updated_credentials": false,
    "successfully_aggregated_at": 1588007610,
    "user_id": "u-1234567",
    "revision": 5097,
    "updated_at": 1588007610,
    "use_cases": ["PFM"],
    "user_guid": "USR-98bdfe3883-2b77-46f8-9e30-39f120e15bfe"
  }
}

​
Member Connection Statuses

Integer ValueStatusDefinitionNext StepsEnd-User Message
nullnullThe member exists but does not have credentials. A member that does not aggregate (e.g., a manual member) will always have this status.None.None.
0CREATEDThe member is new and has not yet been aggregated.Aggregate the member once the end user logs in; poll for a status update.Connecting to […] …
1PREVENTEDMX is preventing aggregation until the member’s credentials have been updated.Display end-user message; after end user has updated their credentials, aggregate again.The last 3 attempts to connect have failed. Please re-enter your credentials to continue importing data.
2DENIEDThe credentials provided for the member were invalid.Display end-user message; after end user has updated their credentials, aggregate again.The credentials entered do not match your credentials at this institution. Please re-enter your credentials to continue importing data.
3CHALLENGEDThe member has been challenged by multi-factor authentication.Display end-user message; follow MFA pathway; after the user answers MFA, poll for a status update.To authenticate your connection to […], please answer the following challenge(s).
4REJECTEDAn MFA challenge was answered incorrectly.Display end-user message; another challenge may follow or aggregation may need to be restarted.The answer or answers provided were incorrect. Please try again.
5LOCKEDThe financial institution is preventing authentication. The end user must contact the financial institution.Display end-user message.Your account is locked. Please log in to the appropriate website for […] and follow the steps to resolve the issue.
6CONNECTEDThe member was successfully authenticated and data is now aggregating.Display the account as having been connected.Connected to […] …
7IMPEDEDThe end user’s attention is required at their online banking institution, e.g., there is a marketing message that must be viewed, terms and conditions that must be accepted, etc.Display end-user message.Your attention is needed at this institution’s website. Please log in to the appropriate website for […] and follow the steps to resolve the issue.
8RECONNECTEDThe member has been migrated to a new data source and aggregation is likely to trigger one-time password MFA. MX will not perform background aggregation in order to avoid unnecessarily disruptive texts, emails, etc. The member must be re-aggregated in the foreground with the end user present.Aggregate the member once the end user logs in; poll for a status update.Reconnecting to […] …
9DEGRADEDAggregation has failed at least three times within a short period of time.Display end-user message.We are upgrading this connection. Please try again later.
10DISCONNECTEDAggregation has failed at least three times and has not succeeded for at least two weeks.Display end-user message.It looks like your data from […] cannot be imported. We are working to resolve the issue.
11DISCONTINUEDThe connection to this financial institution is no longer available.Display end-user message.Connections to this institution are no longer supported. You may create a manual account and use manual transactions to track data for this account.
12CLOSEDThe end user, MX, the client, or a partner has marked the member as closed.Display end-user message.This connection has been closed. You may track this account manually. If reopened, you may connect the institution again.
13DELAYEDAggregating the member has taken longer than expected and it has not yet been connected.Display end-user message; poll for a status update.Importing your data from […] may take a while. Please check back later.
14FAILEDAggregation failed without being connected.Display end-user message; try aggregating again later.There was a problem validating your credentials with […]. Please try again later.
15UPDATEDThe member has been updated — i.e., credentials have been updated — but it has not yet been connected.Aggregate the member once the end user logs in; poll for a status update.Connecting to […] …
16DISABLEDAggregation has been momentarily paused, but the member is still connected.Display end-user message.Importing data from this institution has been disabled. Please contact us if you believe it has been disabled in error.
17IMPORTEDMX does not have credentials and will not try to aggregate the member until the end user provides credentials.Display end-user message; re-aggregate after the end user updates credentials.You must re-authenticate before your data can be imported. Please enter your credentials for […].
18RESUMEDThe answer to an MFA challenge was received, but it is not yet clear whether it was correct.Poll for a status update.Connecting to […] …
19EXPIREDThe MFA answer was not provided within the time allotted by the financial institution.Display end-user message; re-aggregate the member if the end user initiates it.The answer or answers were not provided in time. Please try again.
20IMPAIREDThe member is missing some or all credentials needed in order to connect.Display end-user message; re-aggregate after the end user updates credentials.You must re-authenticate before your data can be imported. Please enter your credentials for […].
21PENDINGThe member is using OAuth to authenticate credentials and still needs to go through the financial institution’s OAuth process. A PENDING status will appear only on members less than one hour old with is_oauth: true. Members that stay PENDING longer than one hour will be deleted by MX.Redirect the end user to the oauth_window_uri provided in the create member response, or request one through the generate OAuth window URI endpoint.None.

​
Member Data Updated

Member data updated webhooks notify you new transaction data is available for the member. It will include a count of new transactions and of updated transactions. This webhook fires only after a completed aggregation event; changes made directly using MX APIs (such as creating or modifying a transaction via Nexus, MDX Real Time, or Batch) will not trigger the webhook. The X-CALLBACK-PAYLOAD header will appear if it was set in the Aggregate Member or Verify Member Platform API request that initiated this webhook.
FieldData TypeDescription
actionStringThis field should always equal member_data_updated.
completed_atIntegerThe time at which the aggregation that triggered the webhook was finished.
completed_onStringThe date on which the aggregation that triggered the webhook was finished.
is_backgroundBooleanThis indicates whether the aggregation was performed manually in the foreground or automatically in the background.
job_guidStringThe unique identifier for the job. Defined by MX.
member_guidStringThe unique identifier for the member which has new or updated transaction data. Defined by MX.
transactions_created_countIntegerThe number of newly created transactions.
transactions_updated_countIntegerThe number of newly updated transactions.
typeStringThe type of webhook being delivered.
user_guidStringThe unique identifier for the user with which the data is associated. Defined by MX.
user_idStringThe unique partner-defined identifier for the user associated with the aggregation.
Example Payload
JSON
{
  "action": "member_data_updated",
  "completed_at": 1531947410,
  "completed_on": "2018-07-18",
  "is_background": true,
  "job_guid": "JOB-823ab268-5107-4a67-97c8-60292572ac2e",
  "member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
  "transactions_created_count": 3,
  "transactions_updated_count": 2,
  "type": "AGGREGATION",
  "user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e",
  "user_id": "partner-defined-id"
}