Overview

This guide helps you troubleshoot webhook behavior in Merge, including delayed delivery, high-volume bursts, missing events, and signature validation issues. Most webhook “issues” stem from sync timing, endpoint handling, or retry behavior rather than webhook failures.

Webhook types in Merge

Merge webhooks (outbound: Merge → your app)

Merge webhooks are requests sent from Merge to your webhook receiver when supported events occur. They are used to notify your application about things like:

• Linked account lifecycle events

• Sync lifecycle events

• Data changes (create, update, delete)

• Async operations (for example, async passthrough completion)

Third-party webhooks (inbound: third party → Merge)

Third-party webhooks originate from the provider and are sent to Merge. Merge uses these webhooks to detect changes in the source system. These webhooks are controlled by the provider, including:

• When events fire and how often

• Payload format and size

• Provider-side retry behavior

How Merge webhooks behave

Merge webhooks follow consistent delivery rules:

• Webhooks (except async passthrough) fire only after a sync completes

• Large syncs can result in many webhook events sent at once

• Merge retries delivery on non-2xx responses

  • Your endpoint should return a 2xx response as quickly as possible (typically within ~30 seconds) to acknowledge receipt.

  • If a webhook request returns a 4xx error (including 429 Too Many Requests), the webhook event is treated as rejected and is not retried.

  • Endpoints that experience sustained failures (such as repeated non-2xx responses or timeouts with no successful deliveries) may be temporarily disabled to prevent further attempts.

If a webhook is disabled, Merge will notify you. Once the issue is resolved, the webhook can be re-enabled.

Troubleshooting Merge webhooks

Verify webhook configuration

1. In your Merge account, go to Advanced → Webhooks.

2. Confirm the target URL is correct and points to the expected environment (staging vs production).

3. Verify the expected event types are enabled.

You can click on Send test POST request to receive a test ping from Merge (note it is not a production-like payload). If the configuration is incorrect, fix it first before investigating delivery behavior.

Check webhook logs

1. In the dashboard, go to Logs → Webhooks, or go to Logs → Webhooks under a given Linked Account.

2. Filter by:

   • Direction: Outbound (Merge → your system)

   • Target URL

   • Approximate timestamp

3. Review each matching entry:

   • Event type

   • Delivery status

   • HTTP response code and body (if any)

This step helps confirm whether Merge attempted to send the webhook and how your endpoint responded. If the webhook did not fire, the event was likely not configured. If it was configured but still didn’t fire, you should verify that the event was being tracked correctly. If the configuration is correct and the event occurred, but no webhook was triggered, please reach out to Merge Support for further assistance.

Response codes and next steps

Determine where the issue is

Use the delivery outcome to narrow the problem:

• 2xx in logs (delivered): Merge reached your endpoint. The issue is usually after receipt—payload/signature/field mismatch, background processing/queues failing, or a logging blind spot.

• Consistent failures/timeouts: The issue is usually before or at receipt—wrong URL/env/path, auth/signature rejection (401/403), routing (404), firewall/WAF/allowlist blocks, or an overloaded/slow endpoint causing 5xx/timeouts (and retries).

• Late/bursty delivery: Check for error/timeout spikes, high-volume events (initial or large syncs/bulk imports), and receiver performance bottlenecks.

Always: return 2xx fast and do the heavy work async.

Verify webhook authenticity

• Validate every request signature: compare X-Merge-Webhook-Signature to the expected value computed from your webhook signing key + raw request body.

• Get the signing key in Merge Dashboard → Webhooks → Security (regenerate if exposed).

• Reject invalid signatures with 401/403.

Troubleshooting third-party webhooks

Third-party webhooks are inbound requests from a provider into Merge.

Troubleshooting in the Merge Dashboard

1. Open the linked account → Webhooks tab:

   1. Confirm third-party webhooks are enabled

   2. Confirm the event/type is supported for that integration

2. Go to Logs → Webhooks: 

   1. Filter Direction = Inbound

   2. Verify the expected events are arriving and not rejected

Troubleshooting in the provider

• Confirm webhooks are enabled for the app/connection

• Verify the destination URL (Merge) and subscribed events

• Check provider delivery logs for errors/throttling

What the results mean

• Provider shows delivered, but nothing in Merge logs → usually provider config or connectivity (network/DNS) between provider and Merge.

• Merge logs show inbound failures → contact Merge Support.

Related documentation:

• Merge Webhooks

• Third-party Webhooks

• Best practices for implementing Merge webhooks