Recap on Existing Webhooks Functionality
The existing functionality of our initial sync, and any sync webhook will remain the same until they are fully deprecated on April 1st, 2024. Any already configured webhooks will not be affected, but you will no longer be able to create new webhooks of these types.
Initial Sync Webhook
These webhooks sent once Merge detected that all common models had attempted a sync upon linked account completion. This webhook would only send if all the common models synced successfully.
Any Sync Webhook
These webhooks sent once Merge completed a sync job for any sync. This webhook would only send if the sync job was successful. If the sync failed for a missing permission, this webhook would not send. This webhook returned the list of models that were updated by the sync job, so it was possible to receive multiple of these webhooks for each common model.
New Webhooks Functionality
Based on recent feedback, we've developed two new types of webhooks to deliver automated updates to you.
Linked Account Linked Webhook
The Linked Account Linked webhook will fire anytime a Linked Account is completed, but before the initial sync is finished. Due to the sensitive nature of the account token, this will be the only webhook that will contain the account token for a given linked account.
As best practice we recommend creating a webhook to be able to read in the account token.
is_relink will indicate if this was an initial Merge Link attempt, or if the end user reauthenticated the account.
"end_user_organization_name": "Example Organization",
"end_user_email_address": "[email protected]",
Common Model Synced Webhook
With the Common Model synced webhook, Merge will send you a webhook each time a common model is done syncing. We recommend using this webhook to manage sync activities at scale and for real-time events.
This new webhook allows you to get notified on a per Common Model basis in order to pull the most updated data. If you only want to sync when all your Common Models are updated, you can wait until all the webhooks (for enabled Common Models) have fired before requesting all data from Merge at once.
end_user_organization_name: "Example Organization",
end_user_email_address: "[email protected]",
synced_fields: ["owner", "remote_data", "subject"],
Linked Account Synced Webhook (Coming in Q4 2023)
Our team is working on a new Linked Account Synced webhook that will notify you once all of the Common Models for a linked account have completed syncing.
This will help those customer that prefer requesting data from Merge when all data is refreshed for an account, instead when each Common Model is individually refreshed.
Migrating Your Webhook Logic
For a more in-depth guide on syncing best practices, we recommend reading our new syncing guide here.
Pulling specific common models
If you would like to implement syncing on a per Common Model basis, we recommend pulling the specific Common Model that are completed from the
Pulling all data
If you would like to be able to sync only when all the Common Models are completed, we recommend implementing a system to monitor the events that have been received from the Common Model Synced webhook. Once you have received a webhook for each model of interest, you can initiate a data pull from Merge.
Once the Linked Account Synced Webhook is launched in Q4, 2023, we recommend using that to get one webhook notification once all data in Merge is refreshed for an account.
Getting the Account Token
If you would like to be able to read in just the account token as a fallback method for Merge Link, or utilize Magic Link, we recommend creating a Linked Account linked webhook.