Payroll Benefit Webhook

Webhooks allow your application to receive real-time notifications when payroll and benefit events occur for your integrated employers. Instead of polling the API for changes, configure a single callback URL and the service will push a notification to it each time an event is triggered.

Configure the Payroll Benefit Webhook:

1. Log in to the developer console.

   • Sandbox Console URL: sandbox.taxbandits.com
   • Live Console URL: console.taxbandits.com

2. Navigate to Settings >> Webhook.

3. Click the Add Webhook button. When selecting the event type, choose Payroll Benefit Webhook.

   Triggered for all payroll and benefit activity, including employee lifecycle, pay period status, benefit management, and daily data sync.

4. Enter your Callback URL and click Save. The service will immediately post a sample JSON payload to the URL. Your endpoint must return an HTTP 200 response to remain active. If the URL does not return 200, it will go inactive. You can retry posting the sample payload from the console to reactivate it.

Webhook Payload

Every notification is delivered as an HTTP POST to your callback URL with a JSON body in the following shape:

{
  "eventType": "employee.created",
  "entity_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "webhook_id": "f9e8d7c6-0000-0000-0000-000000000002",
  "data": { }
}

Field	Type	Description
eventType	string	Identifies the specific event that occurred. See the table below.
entity_id	UUID string	The organization ID of the affected employer. This is the same value used as entity_ids on all API requests.
webhook_id	UUID string	A unique ID for this delivery. Use it to deduplicate retried notifications.
data	object	Event-specific payload. Shape varies by eventType (see below). Absent for job.data_sync_all.completed.

Event Types

The eventType field in each payload tells you exactly what happened. All event types are delivered through the single Payroll Benefit Webhook URL you configured.

Employee Events

eventType	When it fires
employee.created	A new employee's onboarding is fully complete.
employee.updated	An employee's profile fields were updated.
employee.terminated	An employee was terminated.
employee.rehired	A previously terminated employee was rehired.

data shape:

{
  "individual_id": "<employee_id>",
  "isActive": true
}

Pay Period Events

eventType	When it fires
payperiod.completed	A payroll run completed successfully.
payperiod.skipped	A scheduled pay period was skipped.
payperiod.draft	A pay period was returned to draft state.

data shape:

{
  "payment_id": "<payment_id>",
  "status": "completed"
}

Benefit Events

eventType	When it fires
benefit.created	A new employer benefit was activated.
benefit.paused	An employer benefit was paused (set inactive).
benefit.individual.enrolled	An individual was enrolled in a benefit.
benefit.individual.unenrolled	An individual was unenrolled from a benefit.

data shape — benefit.created / benefit.paused:

{
  "benefit_id": "<benefit_id>",
  "isActive": true
}

data shape — benefit.individual.enrolled / benefit.individual.unenrolled:

{
  "benefit_id": "<benefit_id>",
  "individual_id": "<employee_id>",
  "enrollmentStatus": true
}

Benefit Job Events

Asynchronous benefit operations (create, update, enroll, unenroll) run as background jobs. These events report the outcome.

eventType	When it fires
benefit_create.job.completed	A benefit create or update job completed successfully.
benefit_create.job.failed	A benefit create or update job failed.
benefit_enroll.job.completed	A benefit enrollment job completed successfully.
benefit_enroll.job.failed	A benefit enrollment job failed.
benefit_unenroll.job.completed	A benefit unenrollment job completed successfully.
benefit_unenroll.job.failed	A benefit unenrollment job failed.

data shape:

{
  "job_id": "<job_id>",
  "benefit_id": "<benefit_id>"
}

Data Sync Event

eventType	When it fires
job.data_sync_all.completed	The daily data sync job has finished for all businesses.

This event has no data field. The notification is sent to every employer with an active API integration. The entity_id in the payload will be set to each recipient employer's own organization ID.

Delivery and Retry

• Notifications are delivered over HTTPS POST with Content-Type: application/json.
• Your endpoint must respond with HTTP 200 within the request timeout. Any other response code marks the delivery as failed.
• Failed deliveries are retried automatically. If the URL repeatedly fails, it will be marked inactive in the console. Reactivate it by retrying the sample payload from the Webhook settings page.
• Each notification includes a unique webhook_id. Use it to detect and discard duplicate deliveries caused by retries.