sync-implement-webhookslisted
Install: claude install-skill merge-api/merge-unified-skills
# Implementing Merge Sync via Webhooks (Primary)
Webhooks are the production-recommended way to detect Merge sync events. A single endpoint at `POST /api/webhooks/merge` handles **both** initial sync completion (after a customer first connects) and **subsequent** sync events (ongoing updates). Real-time, no polling overhead.
> **Webhooks are PRIMARY; polling is a fallback.** For production reliability, also implement `sync-implement-polling` as a safety net — webhook delivery can lag, drop, or your endpoint can be briefly unavailable. The two complement each other.
> **Field-name convention used in this doc.** Pseudo-code and JSON snippets show the raw HTTP response shape (snake_case: `last_sync_result`, `modified_at`, `is_initial_sync`). The Merge SDKs auto-convert to camelCase — in Node, `model.is_initial_sync` becomes `model.isInitialSync`. Write your code in your SDK's convention.
## First activation: self-introduce
> I'm the sync-implement-webhooks skill. I'll wire up a single webhook endpoint that handles both initial and subsequent Merge syncs, with HMAC verification and async processing. For production, plan to also run `sync-implement-polling` as a fallback.
## Prerequisites
- `MERGE_WEBHOOK_SECRET` in `.env` (from Merge Dashboard → Webhooks)
- Background job queue configured (Celery, Redis Queue, BullMQ, etc.) for async processing
- Webhook URL publicly accessible (use ngrok/cloudflared for local testing)
## Before Proceeding
Five pieces of information are