Connection Webhooks

Payload Attributes

Key	Type	Description
`customerId`	String	Meld's unique identifier for the customer
`connectionId`	String	Meld's unique identifier for the connection that needs to be repaired. Pass this in as the `previousConnectionId` when requesting a connect token for a customer to repair their connection.
`institutionId`	String	Meld's unique identifier for the financial institution
`institutionName`	String	Name of the institution connected to
`reason`	String	Reason the customer needs to repair their connection
`serviceProviderDetails`	Object	If a service provider webhook triggered this event, then this object will contain the raw service provider webhook payload. If there is no associated webhook, this will only contain the service provider name. Note that this object's fields will vary between service providers.
serviceProvider	String	Service provider name

`BANK_LINKING_CONNECTION_COMPLETED`

Sent when the customer completes the connection with their institution. This does not imply that financial account data has completed aggregating or is ready to be fetched.

{
  "eventType": "BANK_LINKING_CONNECTION_COMPLETED",
  "eventId": "NGoTSGJYpd3cLv1iyHWSw9",
  "timestamp": "2021-12-09T21:58:29.329186Z",
  "accountId": "QfdzpX3te1cDaviihXA4D5dA6ghnT3",
  "profileId": "W9kBgKB7afMxYoYuy3rJuZ",
  "version": "2021-10-28",
  "payload": {
    "requestId": "91d7fb355e319532b178acc8a7ae1a69",
    "customerId": "Qg56BnxskKokRV8rVo21Af3T4k6QKY",
    "externalCustomerId": "testCustomer1",
    "connectionId": "WQ4mBt3BEX2cmhCvSPyfTu",
    "institutionId": "Ntj3AwgdridJc2rtfeheku",
    "institutionName": "Chase",
    "serviceProviderDetails": {
      "serviceProvider": "PLAID",
      "serviceProviderConnectionId": "NXrZpLwd1eUQQqymvl9nSkkV8DpeLLUWoXdZx"
    }
  }
}

`BANK_LINKING_CONNECTION_DELETED`

Sent when a connection is deleted. This can happen in response to a customer being deleted (and thus all its connections), the connection being deleted via Meld's API, or the customer revoking access to the connection.

{
  "eventType": "BANK_LINKING_CONNECTION_DELETED",
  "eventId": "NGoTSGJYpd3cLv1iyHWSw9",
  "timestamp": "2021-12-09T21:58:29.329186Z",
  "accountId": "QfdzpX3te1cDaviihXA4D5dA6ghnT3",
  "profileId": "W9kBgKB7afMxYoYuy3rJuZ",
  "version": "2021-10-28",
  "payload": {
    "customerId": "Qg56BnxskKokRV8rVo21Af3T4k6QKY",
    "externalCustomerId": "testCustomer1",
    "connectionId": "WQ4mBt3BEX2cmhCvSPyfTu",
    "institutionId": "Ntj3AwgdridJc2rtfeheku",
    "serviceProviderDetails": {
      "serviceProvider": "PLAID",
      "serviceProviderConnectionId": "NXrZpLwd1eUQQqymvl9nSkkV8DpeLLUWoXdZx"
    }
  }
}

`BANK_LINKING_CONNECTION_STATUS_CHANGE`

{
    "eventType": "BANK_LINKING_CONNECTION_STATUS_CHANGE",
    "eventId": "UhK4iqKP57FeLPgqBi8EUk",
    "timestamp": "2023-08-22T20:54:02.960285Z",
    "accountId": "W9ju7atKP5Jaf5RPweGeis",
    "profileId": "W9kBgKB7afMxYoYuy3rJuZ",
    "version": "2023-07-31",
    "payload": {
      "customerId": "WQ4KqLo3SRSPeTVjxxwo2o",
      "externalCustomerId": "20230822-67a",
      "connectionId": "WQ4KqLuBYYTYHi2YATXYdB",
      "institutionId": "W4AAAFPgUVB85QnQDu5xhU",
      "oldStatus": "ACTIVE",
      "newStatus": "RECONNECT_REQUIRED",
      "newStatusReason": "LOGIN_REQUIRED",
      "activeDuplicateConnectionId": null,
      "serviceProviderDetails": {
        "environment": "sandbox",
        "error": {
          "error_type": "ITEM_ERROR",
          "error_code": "ITEM_LOGIN_REQUIRED",
          "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
          "display_message": null,
          "request_id": null,
          "causes": null,
          "status": 400,
          "documentation_url": null,
          "suggested_action": null
        },
        "item_id": "NXrZpLwd1eUQQqymvl9nSkkV8DpeLLUWoXdZx",
        "serviceProvider": "PLAID",
        "serviceProviderConnectionId": "NXrZpLwd1eUQQqymvl9nSkkV8DpeLLUWoXdZx",
        "webhook_code": "ERROR",
        "webhook_type": "ITEM"
      }
    }
  }

`BANK_LINKING_CUSTOMER_ACTION_REQUIRED`

Sent when a service provider error occurs during an attempted aggregation or when the service provider notifies Meld via their own webhooks that a connection is in a broken state. This can happen when fetching products following an initial connection, or during daily/forced refreshes of existing connections. Following such a webhook, the connection will now have a status of CUSTOMER_ACTION_REQUIRED. Depending on the reason, different actions may need to be taken. The serviceProviderDetails will provide additional information on what caused the connection to end up in such state. A list of potential reasons and actions to take for each of them can be found on the bank linking errors page.

If a connection requires customer action, you can still request information (such as balances, transactions, etc.) about the connection and you will receive the data from the last time the connection was still operational.

{
  "eventType": "BANK_LINKING_CUSTOMER_ACTION_REQUIRED",
  "eventId": "NGoTSGJYpd3cLv1iyHWSw9",
  "timestamp": "2021-12-09T21:58:29.329186Z",
  "accountId": "QfdzpX3te1cDaviihXA4D5dA6ghnT3",
  "version": "2021-10-28",
  "payload": {
    "customerId": "Qg56BnxskKokRV8rVo21Af3T4k6QKY",
    "externalCustomerId": "testCustomer1",
    "connectionId": "WQ4KqLuBYYTYHi2YATXYdB",
    "institutionId": "Ntj3AwgdridJc2rtfeheku",
    "reason": "LOGIN_REQUIRED",
    "serviceProviderDetails": {
      "serviceProvider": "PLAID",
      "webhook_type": "ITEM",
      "webhook_code": "ERROR",
      "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
      "requestId": "1f97b51f3771328bc07187c8a2c1fe30",
      "error": {
        "display_message": null,
        "error_code": "ITEM_LOGIN_REQUIRED",
        "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
        "error_type": "ITEM_ERROR",
        "status": 400
      }
    }
  }
}

`BANK_LINKING_NEW_ACCOUNTS_AVAILABLE`

This webhook is sent when Plaid recognizes that a user with an active connection has opened a new account with the same institution. For example, if a user has a checking account with Chase with an active connection, then later creates a Savings account, you will receive this webhook. If you wish to connect the new account, trigger the repair flow.

{
  "eventType": "BANK_LINKING_NEW_ACCOUNTS_AVAILABLE",
  "eventId": "NGoTSGJYpd3cLv1iyHWSw9",
  "timestamp": "2021-12-09T21:58:29.329186Z",
  "accountId": "QfdzpX3te1cDaviihXA4D5dA6ghnT3",
  "version": "2021-10-28",
  "payload": {
    "customerId": "WGti3bpsethEWYJrm2icuo",
    "externalCustomerId": "20220906-206",
    "connectionId": "WGu7we7dVTCnVkjJrpzVNm",
    "institutionId": "Ntj3AwgdridJc2rtfeheku",
    "serviceProviderDetails": {
      "serviceProvider": "PLAID",
      "webhook_type": "NEW_ACCOUNTS_AVAILABLE",
      "webhook_code": "ITEM",
      "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
      "error": null,
      "environment": "production"
    }
  }
}

`BANK_LINKING_CONNECTION_FAILED`

{
  "eventType": "BANK_LINKING_CONNECTION_FAILED",
  "eventId": "NGoTSGJYpd3cLv1iyHWSw9",
  "timestamp": "2021-12-09T21:58:29.329186Z",
  "accountId": "QfdzpX3te1cDaviihXA4D5dA6ghnT3",
  "version": "2022-03-18",
  "payload": {
    "customerId": "Qg56BnxskKokRV8rVo21Af3T4k6QKY",
    "externalCustomerId": "testCustomer1",
    "connectionId": "WQ4KqLuBYYTYHi2YATXYdB",
    "institutionId": "Ntj3AwgdridJc2rtfeheku",
    "requestId": "1f97b51f3771328bc07187c8a2c1fe30",
    "reason": "UNFORESEEN",
    "serviceProviderDetails": {
      "serviceProvider": "FINICITY",
      "regions":null,
      "serviceProviderConnectionId":"60238343243",
      "payload": {
        "code":102
      }
    }
  }
}

Financial Account Webhooks

Payload Attributes

Key	Type	Description
`customerId`	String	Meld's unique identifier for the customer
`externalCustomerId`	String	Your provided id for the customer
`connectionId`	String	Unique identifier for the connection
`institutionId`	String	Unique identifier for the financial institution
`financialAccounts`	Array of objects	The financial accounts belonging to the connection. Fields vary per event type, and only `id` is guaranteed. Additional fields are detailed in the respective event types.
`id`	String	Unique identifier for the financial account
`serviceProviderDetails`	Object	If a service provider webhook triggered this event, then this object will contain the raw service provider webhook payload. If there is no associated webhook, this will only contain the service provider name. Note that this object's fields will vary between service providers.
`serviceProvider`	String	Service provider name

`BANK_LINKING_ACCOUNTS_UPDATING`

Sent once the connect flow is completed and the accounts are in the process of aggregating. At this time, only basic account info is available. Also sent during subsequent daily/forced refreshes when the accounts are in the process of aggregating again.

Financial Account fields for this event type:

Key	Type	Description
`financialAccounts`	Array of objects
`id`	String	Unique identifier for the financial account
`name`	String	If present, the name of the account as provided by the institution.
`truncatedAccountNumber`	String	If present, the last 4 digits of the account number, sometimes referred to as the account mask.
`newAccount`	Boolean	Indicates if the account was newly added or is an existing account getting updated (i.e. during a refresh)

{
  "eventType": "BANK_LINKING_ACCOUNTS_UPDATING",
  "eventId": "38oVQntsutXnfzn6fZ3mxW",
  "timestamp": "2022-09-06T17:42:49.703620Z",
  "accountId": "W9ju7atKP5Jaf5RPweGeis",
  "profileId": "W9kBgKB7afMxYoYuy3rJuZ",
  "version": "2022-08-29",
  "payload": {
    "customerId": "WGti3bpsethEWYJrm2icuo",
    "externalCustomerId": "20220906-206",
    "connectionId": "WGu7we7dVTCnVkjJrpzVNm",
    "institutionId": "29KL1L2iYUV3zUCoSHhwvr",
    "requestId": "1f97b51f3771328bc07187c8a2c1fe30",
    "financialAccounts": [
      {
        "id": "WGti3dJFc6A9r1pYcBmE6e",
        "name": "Plaid Checking",
        "truncatedAccountNumber": "0000",
        "newAccount": true
      },
      {
        "id": "WGti3cCpeiAtWxL6pFQPTg",
        "name": "Plaid Saving",
        "truncatedAccountNumber": "1111",
        "newAccount": true
      }
    ],
    "serviceProviderDetails": {
      "serviceProvider": "PLAID",
      "serviceProviderConnectionId": "NXrZpLwd1eUQQqymvl9nSkkV8DpeLLUWoXdZx"
    }
  }
}

`BANK_LINKING_ACCOUNTS_UPDATED`

Sent once aggregation has completed for the accounts belonging to the connection. Products are now available to be fetched for the accounts. This webhook should arrive shortly after the BANK_LINKING_ACCOUNTS_UPDATING webhook, but sometimes products may take a while to aggregate for certain institutions. Note that if no products have been updated, then the financialAccounts object in this webhook will be empty. See more about aggregation here.

Financial Account fields for this event type:

Key	Type	Description
`financialAccounts`	Array of objects
`id`	String	Unique identifier for the financial account
`products`	Array of Strings	The products that were updated for the account. This list will never include `TRANSACTIONS` because their updates are handled separately within the transactions webhooks. Products are considered updated even if nothing changed, and it is solely meant to indicate that the updated products were fetched from the service provider.

{
  "eventType": "BANK_LINKING_ACCOUNTS_UPDATED",
  "eventId": "Ja2HXauns8LHPYR1NhEbrh",
  "timestamp": "2022-09-06T17:42:51.853020Z",
  "accountId": "W9ju7atKP5Jaf5RPweGeis",
  "profileId": "W9kBgKB7afMxYoYuy3rJuZ",
  "version": "2022-08-29",
  "payload": {
    "customerId": "WGti3bpsethEWYJrm2icuo",
    "externalCustomerId": "20220906-206",
    "connectionId": "WGu7we7dVTCnVkjJrpzVNm",
    "institutionId": "29KL1L2iYUV3zUCoSHhwvr",
    "requestId": "1f97b51f3771328bc07187c8a2c1fe30",
    "successfullyAggregatedAt": "2023-08-22T19:48:55Z",
    "financialAccounts": [
      {
        "id": "WGti3cCpeiAtWxL6pFQPTg",
        "products": [
          "BALANCES",
          "IDENTIFIERS",
          "OWNERS"
        ]
      },
      {
        "id": "WGti3dJFc6A9r1pYcBmE6e",
        "products": [
          "BALANCES",
          "IDENTIFIERS",
          "OWNERS"
        ]
      }
    ],
    "serviceProviderDetails": {
      "serviceProvider": "PLAID",
      "serviceProviderConnectionId": "NXrZpLwd1eUQQqymvl9nSkkV8DpeLLUWoXdZx"
    }
  }
}

`BANK_LINKING_ACCOUNTS_REMOVED`

Sent when individual financial accounts belonging to a connection have been deleted. This can occur when the customer revokes access to individual accounts or they close a financial account with their bank altogether. This webhook will always be issued following the BANK_LINKING_CONNECTION_DELETED event, as a connection deletion implies all of its financial accounts are deleted as well.

{
  "eventType": "BANK_LINKING_ACCOUNTS_REMOVED",
  "eventId": "GUVQ5N9tQpLFALKpRevt6C",
  "timestamp": "2021-12-09T19:09:23.283931Z",
  "accountId": "QfdzpX3te1cDaviihXA4D5dA6ghnT3",
  "profileId": "W9kBgKB7afMxYoYuy3rJuZ",
  "version": "2021-10-28",
  "payload": {
    "customerId": "WGuEzKYdKukkUFxmzVDUvm",
    "externalCustomerId": "20221031-34",
    "connectionId": "WGuEzMHgUFDzumu6zVRyw5",
    "institutionId": "W9kgBBLULSJFSKTwCpb5Gf",
    "financialAccounts": [
      {
        "id": "WGuEzL3AC3sF155f2ASWpu"
      },
      {
        "id": "WGuEzHzJzEiDTBhCcniN4D"
      },
      {
        "id": "WGuEzHoQA6UgG1Nq1qQ1Qy"
      },
      {
        "id": "WGuEzHswGCZCn2bS1N9Mkh"
      }
    ],
    "serviceProviderDetails": {
      "serviceProvider": "FINICITY",
      "serviceProviderConnectionId": "6026862732"
    }
  }
}

Transaction Webhooks

Payload Attributes

Key	Type	Description
`customerId`	String	Unique identifier for the customer
`externalCustomerId`	String	Your provided id for the customer
`financialAccounts`	Array of objects	List of transaction effects split by financial account
`financialAccountId`	String	The financial account id
`numTransactionsAdded`	Number	If present, number of new transactions available
`numTransactionsUpdated`	Number	If present, number of updated transactions available for the financial account
`transactionsRemoved`	Array of Strings	List of transactions removed for the financial account
`serviceProviderDetails`	Object	If a service provider webhook triggered this event, then this object will contain the raw service provider webhook payload. If there is no associated webhook, this will only contain the service provider name. Note that this object's fields will vary between service providers.
`serviceProvider`	String	Service provider name

`BANK_LINKING_TRANSACTIONS_AGGREGATED`

Captures net transactional effects for each financial account belonging to the connection. Will be sent after each time an aggregation occurs in which transactions are added or modified. See the webhook flow for more details.

{
  "eventType": "BANK_LINKING_TRANSACTIONS_AGGREGATED",
  "eventId": "FEfSjVLXjM81CkG9ejkWBvu3Kb6ND5",
  "timestamp": "2022-01-31T22:05:04.068964Z",
  "accountId": "QfdzpX3te1cDaviihXA4D5dA6ghnT3",
  "version": "2022-03-09",
  "payload": {
    "customerId": "WGv8FTrTroky93FYwAJNXc",
    "externalCustomerId": "testCustomer",
    "connectionId": "WGumJ72d21SDCyma5Ax51k",
    "requestId": "1f97b51f3771328bc07187c8a2c1fe30",
    "successfullyAggregatedAt": "2023-08-22T19:48:55Z",
    "isPartial": false,
    "financialAccounts": [
     	{
        "financialAccountId": "WGv8FSGqrwvgVtqY5CARE9",
        "numTransactionsAdded": 3,
        "numInvestmentTransactionsAdded": 0,
        "numTransactionsUpdated": 1,
        "numInvestmentTransactionsUpdated": 0,
        "transactionIdsRemoved": [],
        "investmentTransactionIdsRemoved": []
     	},
     	{
        "financialAccountId": "WGv8FSsWTrgAXBtS2cVPWR",
        "numTransactionsAdded": 0,
        "numInvestmentTransactionsAdded": 0,
        "numTransactionsUpdated": 17,
        "numInvestmentTransactionsUpdated": 0,
        "transactionIdsRemoved": [],
        "investmentTransactionIdsRemoved": []
     	}
    ],
    "serviceProviderDetails": {
      "environment": "sandbox",
      "item_id": "zqyK7Abwv7cXJnr5Xk9xS31lMgqdXDuo3ZDxb",
      "new_transactions": 8,
      "serviceProvider": "PLAID",
      "webhook_code": "INITIAL_UPDATE",
      "webhook_type": "TRANSACTIONS"
    }
  }
}

`BANK_LINKING_HISTORICAL_TRANSACTIONS_AGGREGATED`

Captures net historical transaction effects for each financial account belonging to the connection. It will be sent out at most once per connection after historical transactions (transactions older than 30 days) have been aggregated. By default, historical transaction aggregation is initiated after the connection is made. This behavior can be changed, see the webhook flow for more details.

{
  "eventType": "BANK_LINKING_HISTORICAL_TRANSACTIONS_AGGREGATED",
  "eventId": "FEfSjVLXjM81CkG9ejkWBvu3Kb6ND5",
  "timestamp": "2022-01-31T22:05:04.068964Z",
  "accountId": "QfdzpX3te1cDaviihXA4D5dA6ghnT3",
  "version": "2022-03-09",
  "payload": {
    "customerId": "WGv8FTrTroky93FYwAJNXc",
    "externalCustomerId": "testCustomer",
    "connectionId": "WGumJ72d21SDCyma5Ax51k",
    "requestId": "1f97b51f3771328bc07187c8a2c1fe30",
    "successfullyAggregatedAt": "2023-08-22T19:48:55Z",
    "isPartial": false,
    "financialAccounts": [
     	{
        "financialAccountId": "WGv8FSGqrwvgVtqY5CARE9",
        "numTransactionsAdded": 84,
        "numInvestmentTransactionsAdded": 0,
        "numTransactionsUpdated": 1,
        "numInvestmentTransactionsUpdated": 0,
        "transactionIdsRemoved": [],
        "investmentTransactionIdsRemoved": []
     	},
     	{
        "financialAccountId": "WGv8FSsWTrgAXBtS2cVPWR",
        "numTransactionsAdded": 150,
        "numInvestmentTransactionsAdded": 0,
        "numTransactionsUpdated": 1,
        "numInvestmentTransactionsUpdated": 0,
        "transactionIdsRemoved": [],
        "investmentTransactionIdsRemoved": []
     	}
    ],
    "serviceProviderDetails": {
      "serviceProvider": "FINICITY",
      "serviceProviderConnectionId": "6026862732"
    }
  }
}