Sage X3 and BambooHR integration

What moves between them

The main flow is BambooHR into Sage X3. Employee records, employment status changes, and job assignments flow from BambooHR into Sage X3 on receipt of a BambooHR webhook or on a polling schedule tied to your HR cycle. Cost center mappings are synchronized in the same direction so that when an employee is hired, transferred, or terminated, the corresponding cost center in Sage X3 is updated to reflect the change. Sage X3 GL accounts and cost center master data are read-only in this flow, so ml-connector does not write back to manufacturing dimensions.

How ml-connector handles it

ml-connector stores BambooHR OAuth credentials encrypted and automatically refreshes the access token every hour. For Sage X3, it accepts the customer's instance URL, port, and folder name, detects whether to use REST api1 or GraphQL Xtrem based on X3 version, and handles the short 5-minute token lifetime by refreshing on every poll. BambooHR webhooks are verified using the SHA-256 HMAC signature in the X-BambooHR-Signature header before processing. When a webhook arrives or a scheduled poll runs, ml-connector fetches the updated employee record from BambooHR, enriches it with job title and cost center from the employee's jobInfo, maps the cost center to the corresponding Sage X3 GL dimension, and upserts the employee into Sage X3's cost center or project structure using the REST api1 or GraphQL endpoint you select. Because BambooHR rate-limits are undocumented and Sage X3 throttling is server-dependent, ml-connector backs off and retries on 429 or 503 responses. All records carry a full audit trail and can be replayed if a downstream Sage X3 call fails.

A real-world example

A mid-sized contract manufacturer runs Sage X3 on-premise for production, procurement, and job costing across multiple facilities. They use BambooHR for payroll and HR. Before the integration, the operations team manually checked the HR org chart every month, looked up which employees were assigned to which cost center, and re-entered any changes into Sage X3's cost center master. When an employee transferred between divisions, the finance team often did not learn about it for weeks, causing labor cost to post to the wrong project. With BambooHR and Sage X3 connected, each hire, termination, and role change in BambooHR flows directly into Sage X3's cost center structure within minutes. Payroll allocations now land on the correct project, month-end reconciliation is faster, and the operations team always sees current staffing.

What you can do

• •Keep Sage X3 headcount and org structure aligned with BambooHR hires, terminations, and role changes.
• •Map BambooHR job titles and cost centers to Sage X3 GL dimensions so labor costs post to the correct projects and departments.
• •Authenticate BambooHR with OAuth 2.0 refresh tokens and Sage X3 with either REST api1 or GraphQL Xtrem depending on your X3 version.
• •Receive BambooHR employee lifecycle webhooks with SHA-256 verification, or poll on a schedule tied to your HR cycle.
• •Handle short token lifetimes, BambooHR rate limits, and Sage X3 transport selection automatically, with retries and a full audit trail on every record.

Questions

Which direction does data move between Sage X3 and BambooHR?

The main flow is BambooHR into Sage X3. Employee records, employment status, job assignments, and cost center mappings flow from BambooHR into Sage X3. Sage X3 GL accounts and cost center master data are read-only in this direction, so ml-connector does not write manufacturing dimensions back into payroll.

Does ml-connector support both REST api1 and GraphQL Xtrem for Sage X3?

Yes. ml-connector detects your Sage X3 version (REST api1 for V6+, GraphQL Xtrem recommended for V12+) and routes accordingly. Both transports require the customer's instance URL, port, and folder name. Access tokens expire in 5 minutes, so ml-connector refreshes on every polling interval to avoid outages.

How does BambooHR webhook verification work?

BambooHR signs webhook payloads with SHA-256 HMAC using your integration secret. ml-connector verifies the X-BambooHR-Signature header on every incoming webhook before processing. If signature verification fails, the webhook is rejected and logged as a security event. Payloads are lightweight, so ml-connector follows up with a GET request to fetch the full employee record including job info and cost center.