What you’ll use
Models - employee, employment, employer benefit, benefit Events -employee_data_changed, connector_synced
Before you start
- A webhook is registered for the environment - see Create a Webhook.
- You can persist a set of employee IDs per connector. Without that, you cannot tell a new hire from an update.
Steps
1
Subscribe to employee changes
Subscribe to Result: A list of employee IDs that changed, and the connector they belong to.
employee_data_changed, and to connector_synced if you need to know the run finished before acting - see Choose Webhook Events.The change event carries IDs, not records:2
Guard against the first sync
On a connector’s first run every employee is new to you, and processing them as hires is not recoverable. Check before doing anything else.Result: Existing employees establish baseline state instead of triggering enrollment.
3
Separate creations from updates
Diff the event’s IDs against the ones you’ve already seen for this connector. Nothing in the payload distinguishes the two - see Created vs modified.Key on the Bindbee
id. remote_id and employee_number can be reissued upstream, which makes an update look like a hire.Result: Only genuinely new employee records.4
Fetch those employees with their employment
Request the IDs directly rather than paging the collection. Result: Full records for the new employees, including their start dates.
start_date and employment_status are both on the employee, so one call is enough.5
Gate on start date, not on arrival
A record appearing is not a hire happening. Future-dated hires arrive weeks early and carry Treat the
PENDING.PENDING to ACTIVE transition as its own signal - offers are withdrawn, and a workflow started on arrival reaches people who never join.Result: Enrollment starts when employment does.6
Read the plans available to them
Fetch the employer’s plan catalog, which is what the employee will be choosing from.This is the plan definition, not anyone’s enrollment - see Reading benefits. Which of these plans a given employee is eligible for is not readable; see the constraint below.Result: The plans to present, per customer.
Constraints specific to this combination
The first sync will look like everyone was hired at once. When a connector is first connected, every employee is new to you. Without a guard, this triggers enrollment workflows for the entire workforce - the failure mode is a welcome email to several thousand existing employees, and it is not recoverable. Handle the initial sync as a bulk import that establishes baseline state without triggering per-employee workflows, then switch to event-driven handling.sync.sync_name increments per run, which is one way to recognize the first. The same applies after a forced resync.
New in Bindbee is not the same as newly hired. A record can appear because the employee was just hired, because they came into scope after a permission or configuration change, or because a prior sync failed to load them. Check the start date rather than treating first-appearance as a hire.
Pre-start records arrive before the person does. Future-dated hires are commonly entered weeks in advance and carry PENDING. That’s useful - it’s the window in which enrollment paperwork should happen - but it means acting on arrival can start a workflow for someone who hasn’t joined and may never join. Offers are withdrawn. Gate on start date, and handle the PENDING to ACTIVE transition as a separate signal.
Eligibility isn’t in the employee model. Waiting periods, hours thresholds, and class-based eligibility rules live in the customer’s benefits configuration, not in anything you can read. You can read the start date and employment type; you cannot read “eligible on 1 October”. Agree the rules per customer and compute eligibility yourself.
The window is short and sync latency eats it. Enrollment windows typically run 30 days from hire, and a 24-hour cadence plus your own processing interval consumes a meaningful share before you begin. Measure the gap between hire date and first contact for a real customer before assuming the schedule is adequate.
Frequently Asked Questions
Every employee arrived as a new hire
Every employee arrived as a new hire
A first sync or a resync. Both re-sync the whole population, so every record looks changed - see modified_after for why. This is what the baseline guard in step 2 exists to prevent.
No event fired though a hire was entered
No event fired though a hire was entered
Change events fire only when a sync actually changes records, and a sync only picks up the hire on its next run. On a Development connector there is no schedule at all - see Development connectors.
A start date is missing or in the past
A start date is missing or in the past
Backdated entries are routine for hires processed late, and
start_date is null on some integrations. Where it is, the employment’s effective_date is the fallback - see Reading employees.An enrollment started for someone who never joined
An enrollment started for someone who never joined
A
PENDING record acted on at arrival rather than at start date. Withdrawn offers and deferred start dates both produce this.