Merge will be deprecating our initial sync, and any sync webhooks on April 1st, 2024.
If you are currently utilizing either or both of these webhook offerings, please ensure that you migrate to our new webhook offerings before this date to prevent any disruptions to your app.
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 three 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.
Example payload:
{
"hook": {
"id": "e8affe31-8ae0-4b37-8c50-d86303094dc4",
"event": "LinkedAccount.linked",
"target": "https://webhook.site/105606a8-cfa3-4415-bae0-954e25137f00"
},
"linked_account": {
"id": "4ac10f37-c656-4e9a-89a1-1b04f9e9a343",
"integration": "Ashby",
"integration_slug": "ashby",
"category": "ats",
"end_user_origin_id": "12345678910",
"end_user_organization_name": "Example Organization",
"end_user_email_address": "[email protected]",
"status": "COMPLETE",
"webhook_listener_url": "https://api.merge.dev/api/integrations/webhook-listener/abcd1234defg5678",
"is_duplicate": false
},
"data": {
"account_token": "<redacted>",
"is_relink": false,
}
}If you are using Magic Link for your customers to link accounts, you must have an Linked Account linked webhook in order to receive the account token from Merge.
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.
Important: The Common Model Synced webhook fires regardless of whether the sync was successful or not. Note that our old webhooks only fired on successful syncs, so we recommend checking the new last_sync_result field to check the status of the sync.
Example Payload:
{
hook: {
id: "e8affe31-8ae0-4b37-8c50-d86303094dc4",
event: "<common_model_name>.synced",
target: "https://webhook.site/105606a8-cfa3-4415-bae0-954e25137f00",
},
linked_account: {
id: "4ac10f37-c656-4e9a-89a1-1b04f9e9a343",
integration: "Ashby",
integration_slug: "ashby",
category: "ats",
end_user_origin_id: "12345678910",
end_user_organization_name: "Example Organization",
end_user_email_address: "[email protected]",
status: "COMPLETE",
webhook_listener_url: "https://api.merge.dev/api/integrations/webhook-listener/abcd1234defg5678",
is_duplicate: false,
},
data: {
sync_status: "PARTIALLY_SYNCED",
integration_name: "Ashby",
integration_id: "ashby",
synced_fields: ["owner", "remote_data", "subject"],
},
}
Linked Account Synced Webhook
With the Linked Account Synced webhook, Merge will notify you once all of the Common Models for a linked account have completed syncing. This will help if you prefer requesting data from Merge when all data is refreshed for an account instead of when each Common Model is individually refreshed.
Important: The Linked Account Synced webhook fires regardless of whether all the syncs were successful or not. Note that our old webhooks only fired on successful syncs, so we recommend checking the new last_sync_result field to check the status of the sync.
Example Payload:
{
"hook": {
"id": "e8affe31-8ae0-4b37-8c50-d86303094dc4",
"event": "LinkedAccount.sync_completed",
"target": "https://webhook.site/105606a8-cfa3-4415-bae0-954e25137f00"
},
"linked_account": {
"id": "4ac10f37-c656-4e9a-89a1-1b04f9e9a343",
"integration": "Ashby",
"integration_slug": "ashby",
"category": "ats",
"end_user_origin_id": "12345678910",
"end_user_organization_name": "Example Organization",
"end_user_email_address": "[email protected]",
"status": "COMPLETE",
"webhook_listener_url": "https://api.merge.dev/api/integrations/webhook-listener/abcd1234defg5678",
"is_duplicate": false,
"account_type": "PRODUCTION"
},
"data": {
"is_initial_sync": true,
"integration_name": "Ashby",
"integration_id": "ashby",
"sync_status": {
"ats.RemoteUser": {
"last_sync_finished": "2023-12-29T18:53:09Z",
"last_sync_result": "DONE"
},
"ats.Candidate": {
"last_sync_finished": "2023-12-29T18:57:12Z",
"last_sync_result": "PARTIALLY_SYNCED"
},
"ats.Application": {
"last_sync_finished": "2023-12-29T18:59:25Z",
"last_sync_result": "DONE"
},
"ats.Job": {
"last_sync_finished": "2023-12-29T17:05:45Z",
"last_sync_result": "FAILED"
}
}
}
}
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 Models that are completed from the hook.event field.
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.
If you want to only pull data when all Common Models have synced, we recommend using the Linked Account Synced webhook 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.