Configure Merge webhooks that send data payloads to your app.
When you've connected to Merge, you'll want to know when data in your linked integrations is updated so that you know when to sync data, keeping your own database up to date. Instead of polling for data on a recurring basis - which can be inefficient and result in timing conflicts - webhooks will push alerts to your API at the time that relevant data is updated.
In this guide, you'll learn how to add and manage these webhooks. Webhooks will come in the form of inbound POST requests to your API, which you can use to trigger the creation, update, or deletion of data in your system to mirror some event in Merge, or any other action you want - you are only limited by the code you can write.
Webhooks are shared amongst your Merge organization.
To create webhooks, go to the Webhooks management console under the Advanced configuration in your Merge dashboard and click +Webhook.
On the next page, add the URL that you want Merge to send a POST request to. This URL should point to a POST route in your API that you'll build to handle the incoming payload.
Make sure to select the event types that you want to trigger the webhook. We recommend selecting “Send me data when anything is created or updated” and detecting the affected data models within your API by parsing the JSON payload.
If you want to test your webhook, use the button labeled “Send test POST request”. This will cause Merge to send a POST request carrying a sample payload to the URL you've specified, where you can log the output and program your endpoint to do something in response to the payload.
hookObjectlinked_accountStringdataObjectMerge supports 6 webhook event types. Click each event type below to see an example payload.
Receive an alert when a new Linked Account is linked.
You'll want to ensure that your API endpoint is verifying that incoming POST requests are from Merge and not a malicious source, and that payloads haven't been altered in transit.
The best way to do that is to check that the X-Merge-Webhook-Signature field in the header of the incoming request matches an encoded combination of your organization's webhook signature and the payload attached to the incoming request.
In your Webhooks page under configuration, you should see a Security module with your signature key. This key is unique to your organization and can be regenerated if it ever becomes known by an untrusted third party.