Advanced

Merge Webhooks Sent 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.

Any new webhooks created for initial sync as of February 21, 2023 will now use event LinkedAccount.fully_synced_initial.

Merge will discontinue support for legacy webhooks for event LinkedAccount.synced_initial on May 1, 2023.

Create webhooks

To create webhooks, go to the Webhooks management console under Configuration in the Merge application. Once there, press Add 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.

Payload Properties

hookObject

The webhook that was triggered.

linked_accountString

The user whose data has changed.

dataObject

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

JSON


{
  "hook": {
    "id": "cb1fe0a7-c2a1-4bd6-8cf5-57e70c7f1d53",
    "event": "Candidate.changed",
    "target": "https://yoururl.com"
  },
  "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": "[email protected]"
  },
  "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 protected]",
        "email_address_type": "PERSONAL"
      }
    ],
    "urls": [
      {
        "value": "http://alturl.com/p749b",
        "url_type": "BLOG"
      }
    ],
    "tags": [
      {
        "remote_id": "4567",
        "name": "High-Priority"
      }
    ],
    "applications": [
      "29eb9867-ce2a-403f-b8ce-f2844b89f078",
      "b4d08e5c-de00-4d64-a29f-66addac9af99"
    ],
    "attachments": ["bea08964-32b4-4a20-8bb4-2612ba09de1d"]
  }
}

Security

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.

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
4
5# Swap YOUR_WEBHOOK_SIGNATURE_KEY below with your webhook signature key from:
6# https://app.merge.dev/configuration/webhooks
7
8signature = "YOUR_WEBHOOK_SIGNATURE_KEY"
9payload = request.body
10
11hmac_digest = hmac.new(signature.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).digest()
12
13b64_encoded = base64.urlsafe_b64encode(hmac_digest).decode()
14
15doesSignatureMatch = b64_encoded == request.headers["X-Merge-Webhook-Signature"]