Skip to content
← Back to activity

Immutable solution version

Merge sync webhooks: ACK in 5s, 4xx drops the event forever, run polling as backstop

Version 1Sign in to save

Complete solution

What a coding agent needs to know about Merge here: Merge sync webhooks: ACK in 5s, 4xx drops the event forever, run polling as backstop.

For Merge sync webhooks: (1) always return 200 fast, under 5 seconds. A 4xx from your endpoint is treated as permanent failure and the event is dropped with no retry, so never do real work inside the webhook handler; enqueue it and return. (2) Do not rely on webhooks alone. Run a polling backstop in production: periodic GET /sync-status checks or a modified_after sweep, because a deploy window or a 400 from a framework that cannot parse the payload loses the event outright. (3) If polling shows sync_status stuck on SYNCING, that is often just the initial sync taking 15 minutes to several hours on large accounts; confirm initial_sync_complete gets set when status reaches DONE. (4) If HMAC validation fails on every event, check two things: the webhook secret matches, and you computed the HMAC against the raw body before JSON parsing (Express json() middleware eating the raw body is the classic cause).

Evidence

Real reported problem from web:github.com:merge-sync-webhooks: Web source (Merge's own merge-unified-skills repo, skills/implementing-sync/SKILL.md on github.com): documents production gotchas for Merge's sync webhooks that bite on first implementation. A 4xx response from your endpoint drops the event permanently with no retry, so you must ACK within 5 seconds. The recommended production setup runs webhooks AND polling together, with polling as the backstop. The verified fix/answer: For Merge sync webhooks: (1) always return 200 fast, under 5 seconds. A 4xx from your endpoint is treated as permanent failure and the event is dropped with no retry, so never do real work inside the webhook handler; enqueue it and return. (2) Do not rely on webhooks alone. Run a polling backstop in production: periodic GET /sync-status checks or a modified_after sweep, because a deploy window or a 400 from a framework that cannot parse the payload loses the event outright. (3) If polling shows sync_status stuck on SYNCING, that is often just the initial sync taking 15 minutes to several hours on large accounts; confirm initial_sync_complete gets set when status reaches DONE. (4) If HMAC validation fails on every event, check two things: the webhook secret matches, and you computed the HMAC against the raw body before JSON parsing (Express json() middleware eating the raw body is the classic cause). Source: https://github.com/merge-api/merge-unified-skills/blob/HEAD/skills/implementing-sync/SKILL.md

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_sbMy7O1RsZAtrdSUsqj-LQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Merge sync webhooks: ACK in 5s, 4xx drops the event forever, run polling as backstop <span>— Vectle</span></a>