Overview

Merge webhooks enable your systems to react to changes in Merge as soon as they happen. To ensure reliable, secure, and scalable usage of Merge Webhooks, we strongly recommend following the best practices in this guide.

Verify the webhook signature

To ensure that incoming webhook requests are truly from Merge and their payloads haven’t been tampered with, you should always validate the signature included with every webhook.

Merge signs each webhook using a combination of your organization’s webhook signature secret and the raw request payload. This value is provided in the X-Merge-Webhook-Signature header of each POST request.

Your receiver should:

• Extract the signature from the X-Merge-Webhook-Signature header

• Independently compute the expected signature using your secret + payload

• Compare the computed signature with the incoming signature

• Reject the request if they don’t match

Refer to our official webhooks documentation for full implementation details, including sample code snippets.

Do not fully rely on webhooks

Webhooks are powerful, but like all network-dependent workflows, they are inherently susceptible to outages, latency, or failed processing on the receiving end.

Merge attempts does retry failed requests using exponential backoff, but if your receiver remains unavailable or fails to process messages, you may miss important changes.

To ensure data integrity, we strongly recommend:

• Continuously receiving webhooks for real-time updates

• Supplementing with periodic polling (e.g., once every 24 hours) to reconcile any missed events

This hybrid approach ensures full accuracy, even in the event of webhook failures.

Handle webhooks asynchronously

Webhook receivers should acknowledge delivery as quickly as possible. Any substantial processing performed inside the incoming HTTP request will cause:

• Timeouts and subsequent retries

• Increased load during spikes in webhook volume

• A higher risk of dropped or duplicated processing

Instead, your receiver should:

1. Return a 2xx response immediately

2. Queue the payload for downstream asynchronous processing

This pattern improves performance, reliability, and cost efficiency for both your system and Merge.

Prepare for spikes if using Changed Data webhooks

Changed Data webhooks fire one webhook per individual change. If a bulk update is performed in third-party system, your webhook receiver may experience a sudden burst of incoming requests.

To handle these spikes safely:

• Prioritize asynchronous processing

• Ensure your infrastructure can autoscale or buffer traffic

• Monitor queue depth and processing throughput

Using webhooks across multiple environments

Merge sends webhooks for both Test and Production Linked Accounts. If you manage multiple environments (e.g., DEV, PROD), you have two options:

Recommended: Create separate Merge organizations for each environment

• There is no additional cost - Merge sums all Production Linked Accounts across your orgs when calculating usage, so use Test Linked Accounts in non-production orgs.

• Reach out to your CSM for help configuring this setup!

Alternative: Drop or ignore cross-environment webhooks

• In your PROD environment, ignore all webhooks associated with Test Linked Accounts

• In non-production environments, ignore all webhooks from Production Linked Accounts

How to identify unique webhooks

You many want to protect certain webhook receivers against double-processing. The most reliable way to detect duplicates is by using the webhook signature.

Each webhook’s X-Merge-Webhook-Signature value is unique to that specific event, so you can:

• Treat the signature as an idempotency key

• Cache previously processed signatures

• Skip processing when a duplicate signature is detected

This helps avoid accidental reprocessing due to retries or network behavior.

Other tips & common questions

Sample payloads & interfaces

Our SDKs do not currently include typed webhook interfaces. However, you can find complete sample payloads in our official webhook documentation to help with validation, typing, and testing.

Why would a webhook be disabled?

Your Merge webhook could be disable for one of two reasons:

• Your receiver experiences a sustained spike in failures (e.g., repeated non-2xx responses or timeouts) with no successes

  • Merge will notify you if this occurs

  • We will re-enable when you confirm your receiver is fixed

• Your receiver has only failed (not successes) for 72 hours straight

  • After 24 hours of failures, you will receive an automated email that your webhook will be turned off in 48 hours

  • You can manually re-enable in the Merge Dashboard when your receiver is fixed

We recommend monitoring system availability and setting up alerting on failure spikes.