In the Merge dashboard or via the Merge API, register a webhook URL and select the HRIS object types and change events you want to monitor (e.g., employee created, employment terminated, compensation updated)
Implement an HTTPS endpoint in your application to receive Merge webhook POST payloads; return HTTP 200 promptly to acknowledge receipt
Validate webhook signatures using the secret provided in the Merge dashboard to ensure payloads originate from Merge
Parse the webhook payload to extract the linked_account_id (to identify which employer's data changed), the object_type, the change_type, and the modified object data
Trigger your downstream workflow based on change type: e.g., provision accounts for new employees, revoke access on terminations, update compensation records in your people analytics DB
Handle the case where the full object is not included in the webhook — fetch the complete record from the Merge API using the object ID in the payload if you need additional fields
Known gotchas
Merge webhooks reflect changes detected during Merge's periodic sync cycles, not real-time events from the source payroll system — there may be a delay between when a change occurs in the source system and when Merge delivers the webhook
Webhook payloads may not always include the full object; design your handler to re-fetch the object from the Merge API when the payload is a slim reference rather than the complete record
Linked account IDs in webhook payloads identify the specific employer integration — without this context, you cannot know which employer's employee changed; always index stored data by linked_account_id
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp