Skip to main content
This page walks developers through both halves of the webhook setup for Bank Linking: configuring your service providers to deliver webhooks to Meld, and configuring Meld to deliver webhooks to your backend.

​
Before you begin

​
Introduction

Meld uses webhooks to send you real-time updates when an event happens in your account — for example, a customer connects with new financial accounts, or new updates have been made to a customer’s financial accounts and/or transactions. The webhook flow:
  1. Meld receives a webhook from the service provider that an action has happened.
  2. Meld processes the webhook.
  3. Meld sends you a corresponding webhook letting you know what happened.
This means you receive only webhooks from Meld, not the service provider, and the format and data are standardized across providers. Two distinct webhook setups are required: one for the service provider to send webhooks to Meld, and one for Meld to send webhooks to you.

​
Environments

Meld offers both production and sandbox environments. The base URL for each is:
EnvironmentAPI Base URL
Sandboxhttps://api-sb.meld.io
Productionhttps://api.meld.io
The same webhook flow applies in both environments, but each environment has its own API key and its own webhook URLs in the Dashboard. Set webhooks up separately for sandbox and production.

​
Steps to send webhooks from the service provider to Meld

For accounts that Meld shares with you (these show as “Shared Meld Integration” in the Dashboard), webhooks from the provider to Meld have already been set up — no work is needed on your part. Also, some service providers (such as Robinhood) don’t support webhooks, so no setup is needed for those either.
  1. In the Meld Dashboard, open the Integrations tab and locate your Meld webhook URL. Webhook URLs are per service provider, per environment (sandbox and prod) — view the URL for any provider by clicking on it and expanding it. The URL clearly indicates which environment and which service provider each link is for. If in doubt, reach out to Meld. Integrations tab showing webhook URL
  2. Take the webhook URL from the Meld Dashboard and add it in the service provider’s dashboard so that the provider sends Meld webhooks for your account. Events vary between providers — to be safe, sign up for all available events.
Not all service providers have a dashboard. For those that don’t, you may need to reach out to them directly so their team can set this up. Once both steps are complete, Meld starts receiving webhooks from the service provider whenever transaction or connection information changes, and forwards that information to you in Meld’s outbound webhooks (see the next section).

​
MX Webhooks

MX specifically requires a webhook username and password when setting up webhooks to Meld. However, Meld needs your MX API Key and Client ID before generating a URL for you to use to set up webhooks in the MX dashboard. Therefore, when setting up an MX integration, the recommended order of operations is:
  1. Add your MX API Key and Client ID in the Meld Dashboard.
  2. After Meld provides you with a Meld webhook URL, use that URL to set up a webhook profile on MX’s dashboard, along with a username and password.
  3. Return to Meld’s Dashboard and add the username and password to the MX integration credentials.
MX webhook credentials

​
Steps to receive webhooks from Meld

All of the steps for configuring webhooks to be sent to you from Meld can also be done through the UI in the Developer tab of the Meld Dashboard, which Meld recommends for ease of use. Webhooks UI in Dashboard
  1. Click Add Endpoint, add your URL, and name the webhook profile. Add endpoint modal
  2. Select the events you want to receive webhooks for. Meld recommends subscribing to all webhooks so you don’t miss any updates. Event selection
  3. Click Add Endpoint to save.

​
Setting up webhooks via the API

If you prefer to set up webhooks through the API rather than the Dashboard: Step 1. Using the API Key Meld has issued to you, send a GET request to {api_base_url}/notifications/webhooks/event-types. You will receive a list of all event types available.
Your API Key is a secret — treat it as such. Do not share it or send it through a frontend call.
Sample request: 
curl --location --request GET '{api_base_url}/notifications/webhooks/event-types' \
  --header 'Authorization: BASIC {{Your API Key}}'
Sample response: 
[
   "BANK_LINKING_CONNECTION_COMPLETED",
   "BANK_LINKING_CONNECTION_DELETED",
   "BANK_LINKING_CUSTOMER_ACTION_REQUIRED",
   "BANK_LINKING_ACCOUNTS_UPDATING",
   "BANK_LINKING_ACCOUNTS_UPDATED",
   "BANK_LINKING_ACCOUNTS_REMOVED"
]
Step 2. Identify the events you want to monitor and the event payloads you will need to parse. See Bank Linking Webhook Events. Step 3. Using your API Key, send a POST request to {api_base_url}/notifications/webhooks. You will receive a 201 Created status code and details of your webhook profile. Sample request: 
curl --location --request POST '{api_base_url}/notifications/webhooks' \
  --header 'Authorization: BASIC {{Your API Key}}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "sample-webhook-profile-name",
    "url": "https://a875ba2afae4f7792f48c28cd16e72b8.m.pipedream.net",
    "eventType": ["FINANCIAL_ACCOUNT_ADDED",
        "FINANCIAL_ACCOUNT_TRANSACTIONS_ADDED"]
  }'
Sample response: 
{
    "id": "Qg571FiGTbdzH2KPUwtXYi6yM6coJY",
    "accountId": "Qg5735bhbj8RnyJ2G5urbfBsAncbTX",
    "name": "sample-webhook-profile-name",
    "status": "ACTIVE",
    "url": "https://a875ba2afae4f7792f48c28cd16e72b8.m.pipedream.net",
    "secret": "aUAMGr4swsCJ2JoBV2JsyLzdh1somQH9QM2ibzGByK9iky4Jg21eG",
    "eventVersion": "2022-01-31",
    "eventTypes": null
}
Your webhook profile is now ready to receive notifications from Meld at the URL you specified. Meld recommends using webhook signatures to verify that requests originated from Meld and were not sent by a third party — see Webhook Authentication.
When you created a profile, Meld sent a WEBHOOK_TEST event to the designated URL right away. If you do not receive a WEBHOOK_TEST webhook:
  • Do a health check on your webhook source.
  • Check that the webhook is pointing to the right destination.
  • Make sure your destination server is running.
You can also reach out to Meld for assistance.
Step 4. Use the below endpoints to update webhook profiles, list all your webhook profiles, or get details of a specific webhook profile.
UsageEndpoint
Update your webhook profilePATCH /notifications/webhooks/{webhookProfileId}
List all your webhook profilesGET /notifications/webhooks
Get details of a specific webhook profileGET /notifications/webhooks/{webhookProfileId}
Resources