Merge Docs


Use Merge's two types of webhooks to keep your application up to date in real-time.


Merge offers two types of webhooks to ensure data is up to date:

Webhooks Sent from Third-Parties to Merge

Merge has the ability to receive webhooks emitted by third-party applications. When an end-user makes a change to their third-party application, such as an HRIS or ATS platform, that platform will know to send Merge a webhook with the relevant payload. This will happen regardless of rate at which Merge normally syncs its data, thus allowing you to have access to real-time updates.

The section below demonstrates how to enable Merge to receive third-party webhooks for a given linked account.

Set Up

Enabling Merge to receive webhooks begins in the Merge dashboard. Navigate to Linked Accounts, and select a linked account integrated with a third-party platform that supports the ability to send webhooks. Look under the "Webhooks" section to:

  • Access the Listener URL for a given linked account
  • Configure which events Merge will listen to

Note: You will need to guide your user to add the Listener URL to their third-party application.

Webhooks Sent from Merge to You

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.

Create webhooks

To create webhooks, go to the Webhooks management console under Configuration in the Merge application. Once there, press Add webhook.

Preview of webhooks list

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 “All data types and events” and detecting the affected data models within your API by parsing the JSON payload.

Preview of adding webhooks

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.

Payload Properties

The webhook that was triggered.

The user whose data has changed.

The affected data model. The structure of each model can be found in our API documentation

See an example of the JSON payload below:

Webhook Payload Example
"hook": {
"id": "cb1fe0a7-c2a1-4bd6-8cf5-57e70c7f1d53",
"event": "Candidate.changed",
"target": ""
"linked_account": {
"id": "a3602c03-aba7-4d9d-a349-dbc338504092",
"integration": "Zenefits",
"end_user_origin_id": "23423464",
"end_user_organization_name": "Your Beautiful Customer",
"end_user_email_address": ""
"data": {
"id": "22582af6-b45e-4d34-bed6-77bb40effa97",
"remote_id": "97134123",
"first_name": "Gil",
"last_name": "Feig",
"company": "Columbia Dining App.",
"title": "Software Engineer",
"remote_created_at": "2020-11-11T00:59:25.309761Z",
"remote_updated_at": "2020-11-11T00:59:25.309761Z",
"last_interaction_at": "2020-11-11T00:59:25.309761Z",
"is_private": true,
"can_email": true,
"locations": ["San Francisco", "New York", "Miami"],
"phone_numbers": [
"value": "+1234567890",
"phone_number_type": "MOBILE"
"email_addresses": [
"value": "",
"email_address_type": "PERSONAL"
"urls": [
"value": "",
"url_type": "BLOG"
"tags": [
"remote_id": "4567",
"name": "High-Priority"
"applications": [
"attachments": ["bea08964-32b4-4a20-8bb4-2612ba09de1d"]


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.

Preview of webhooks security

Using this key, calculate the HMAC-SHA256 of the byte-formatted payload and encode it to Base64url to get a digest. Ensure that the digest matches the X-Merge-Webhook-Signature found in the headers of the incoming POST request to confirm that the request is valid.

Securing Webhooks
1import base64
2import hashlib
3import hmac
5# Swap YOUR_WEBHOOK_SIGNATURE_KEY below with your webhook signature key from:
9payload = request.body
11hmac_digest ="utf-8"), payload, hashlib.sha256).digest()
13b64_encoded = base64.urlsafe_b64encode(hmac_digest).decode()
15doesSignatureMatch = b64_encoded == request.headers["X-Merge-Webhook-Signature"]

Webhook Visibility

All Webhooks are visible as Logs, and viewable from Merge's dashboard.

Merge Link demo in dashboard