Company Webhook Events

Audience: company. These events are about one company and are sent to that company's own webhook endpoints. They use the company envelope, which always has companyId. For the difference between company webhooks and partner webhooks, start with the Webhooks Overview.

Each company instance can have up to three webhook endpoints.

• Through the API: manage endpoints with the Webhook Endpoints API, using the company's API key. You can list, add, change, switch off and delete endpoints, rotate an endpoint's signing key, and send a test event. In Payroll Infrastructure you can also set the first at company creation.
• In the Everee admin portal: hosted payroll customers can configure the same endpoints in the "Settings > Integrations Hub" screen, under the section called "Everee API". To stop receiving events at an endpoint, delete it from the same screen.

Your Sandbox and Production instances each have their own endpoints and signing keys. See Sandbox & Production.

All of the events on this page are sent to every webhook endpoint by default. No configuration or request to Everee is needed to start receiving any of them.

Events at a glance

Company events documented on other pages:

• payroll-run.*, net-payout.* and requirement.*: sent as a company's payroll runs are calculated, approved, funded and paid. See Payroll Run Events.
• company-onboarding.*: sent while a company you created moves through onboarding. See Company Onboarding Events.
• announcement.published, announcement.updated, announcement.retracted: sent to companies that use Everee directly. See Announcement Events.
• test-event.created: sent by Send a test event.

The company envelope

When a company event is sent to your target URL, the payload has the following structure. companyId is always present and partnerId never is. Every request also has the header x-everee-webhook-audience: company. The envelope is defined as a JSON Schema.

{
	"version": "1", // version of the payload structure; currently always "1"
	"id": "abcdef-...",
	"companyId": 10011, // unique ID of the client Company instance in Everee
	"type": "event.type-name", // event type name (see above)
	"timestamp": 17200110020, // epoch timestamp of the event’s occurrence
	"data": {
		"object": {
			[relevant object structure; see below]
		}
  }
}

Worker Onboarding Completed

This event is sent when a worker has completed onboarding in Everee and is ready to receive funds.

Webhook event type: worker.onboarding-completed
Webhook event data.object has the following structure:

{
  "workerId": "workerId",
  "externalWorkerId": "externalWorkerId",
  "onboardingStatus": "COMPLETE",
  "onboardingComplete": true
}

Worker's Preferred Payment Method Changed

This event is sent when a worker's preferred payment method has been changed. If you offer both Direct Deposit and Pay Card to workers, you may receive this event multiple times at the worker's discretion. If you are transitioning workers from one payment method to another, you'll receive this event to indicate that the worker has transitioned to the target payment method.

The fields directDeposit or payCard are mutually exclusive: only one will be true at any time.

Webhook event type: worker.updated-payment-method
Webhook event data.object has this structure:

{
  "workerId": "workerId",
  "externalWorkerId": "externalWorkerId",
  "directDeposit": false,
  "payCard": true
}

This event reports the worker's choice. It isn't sent when Everee itself changes the preferred method, for example when a company's available payment methods change and a new worker is switched to the Pay Card automatically. A worker whose preferred method is the Pay Card may not have a card yet. To know when a worker's card exists, use the Pay Card Signup Completed event.

Worker Pay Card Signup Completed

This event is sent when a worker has finished signing up for the Everee Visa® Pay Card, so their card account exists. It's sent once per worker, the first time their Pay Card signup is completed. That includes a worker who signs up through the embedded Pay Card signup experience, and a worker who already has an Everee Pay Card from another company and picks it as their payment method here.

It isn't sent for a worker who only has the Pay Card as their preferred payment method, or who finishes onboarding without signing up for a card. Like the other events on this page, it's sent to every webhook endpoint with no extra setup.

If you need to know when a worker is ready to be paid, use worker.onboarding-completed. The two events are separate, and don't arrive in a guaranteed order.

Webhook event type: worker.pay-card-signup-completed
Webhook event data.object has the following structure. The example values are made up.

{
  "workerId": "workerId",
  "externalWorkerId": "externalWorkerId",
  "payCardSignupComplete": true
}

payCardSignupComplete is always true.

New Tax Forms Available

This event is sent when Everee detects that a worker has been paid in a new tax jurisdiction for the first time, and there are one or more new tax withholding forms available for the worker to fill out.

This will occur any time wages (like timesheet hours or payable items) are entered into Everee with an associated Work Location, the worker hasn't been paid at that Work Location before, and the Work Location is in a different tax jurisdiction from anywhere they've worked before, like in a new state.

When you receive this event, you can direct the worker to fill out the new tax form(s) either by signing into the Everee worker-facing web portal, or accessing the Embedded Tax Forms experience within your own product. The new tax form(s) will be shown there, ready to be filled out.

Webhook event type: worker.new-tax-forms-available
Webhook event data.object has this structure:

{
  "workerId": "workerId",
  "externalWorkerId": "externalWorkerId"
}

Worker Payment Processed

This event is sent when a payment to a worker has been successfully processed for deposit (for ACH, has been submitted to the ACH network for settlement).

Webhook event type: payment.paid
Webhook event data.object has the following structure:

{
  "workerId": "workerId",
  "externalWorkerId": "externalWorkerId",
  "paymentId": 98765432,
  "earningDate": "2025-08-01",
  "payPeriodStartDate": "2025-07-19",
  "payPeriodEndDate": "2025-08-01",
  "payDate": "2025-08-06",
  "shiftIds": [123456, 123457],
  "shifts": [
    { "shiftId": 123456, "externalId": "timesheet-entry-1" },
    { "shiftId": 123457 }
  ],
  "timesheetEntryExternalIds": ["timesheet-entry-2"],
  "grossAmount": { "amount": "500.00", "currency": "USD" },
  "netAmount": { "amount": "441.21", "currency": "USD" },
  "payables": [
    {
      "externalId": "payable-id-1",
      "payCodeType": "EARNING",
      "payCode": "STIPEND",
      "amount": { "amount": "500.00", "currency": "USD" },
      "date": "2025-08-01"
    }
  ],
  "costCenters": [
    { "costCenterName": "department", "costCenterValue": "Engineering" }
  ]
}

The shifts array lists the same shifts as shiftIds, each paired with the externalId you supplied when you added or updated the shift. A shift that was entered without an externalId has no externalId field.

The timesheetEntryExternalIds array lists the externalIds of the classified-hours entries this payment paid, as you supplied them to Update classified hours for pay period (bulk). These entries aren't shifts, so they don't appear in shiftIds or shifts. Entries sent without an externalId aren't listed.

The payables array lists the payable items in the payment that you submitted through the API, each with its externalId.

The costCenters array lists the cost centers the payment's wages were coded to. In each entry, costCenterName is the cost center's key (the costCenterKey you use in the Cost Center API), not its display name, and costCenterValue is the value within it.

Payable Items' Payment Status Changed

This event is sent when one or more payable items, all processed together in a single payment for payout to a worker, have changed their payment status either to "error", which indicates that they are temporarily blocked from being paid-out, or "paid", which indicates that they have been transferred (or for ACH, have been submitted to the ACH network for settlement).

The possible values of the paymentStatus field are PAID or ERROR.

Webhook event type: payment-payables.status-changed
Webhook event data.object has the following structure:

{
  "workerId": "workerId",
  "externalWorkerId": "externalWorkerId",
  "paymentId": 98765432,
  "earningDate": "2025-08-01",
  "payableExternalIds": [
    "payable-id-1",
    "payable-id-2"
  ],
  "paymentStatus": "PAID",
  "paymentErrorMessage": "An error message, populated only if paymentStatus is 'ERROR'."
}

Payment ACH Deposit Returned

This event is sent when a payment ACH deposit has been returned by the destination bank.

This is most often due to an incorrect account/routing number in Everee. The client should prompt the worker to update their account/routing number information. When account/routing number information has been updated, Everee will automatically retry the deposit as soon as possible.

The payment keeps the same paymentId throughout; a retry doesn't create a new payment. A return can affect only part of a payment (for example, when a worker splits their pay across accounts), and you may receive this event more than once for the same payment if a retry is returned again. Each retry attempt is announced by a payment.deposit-retried event. No event is sent when a retry settles. See Returned Deposits and Retries for how to track the outcome.

Webhook event type: payment.deposit-returned
Webhook event data.object has the following structure:

{
	"workerId": "workerId",
	"externalWorkerId": "externalWorkerId",
	"paymentId": 123456789
}

Payment ACH Deposit Retried

This event is sent when Everee queues a retry of a returned ACH deposit for distribution. It follows a payment.deposit-returned event.

Actions that trigger this event include:

• The worker corrects their bank account and Everee automatically retries the deposit
• Everee Support retries the deposit, or re-sends it to a different bank account the worker has on file

The event reports that a retry attempt was attempted, but since ACH is an asynchronous system, it doesn't mean the funds have successfully posted to the destination account yet. If the retry is returned again, you receive another payment.deposit-returned event, and the cycle repeats.

The payment keeps the same paymentId; the retry appears as a new payout on that payment. See Returned Deposits and Retries.

Webhook event type: payment.deposit-retried
Webhook event data.object has the following structure:

{
	"workerId": "workerId",
	"externalWorkerId": "externalWorkerId",
	"paymentId": 123456789
}

Worker Profile Created

This event is sent when a worker's profile has been created.

Actions that trigger this event include:

• Creating an employee or contractor profile via API
• Manually adding worker profiles using the one-time or bulk workflows in the Everee admin portal

Webhook event type: worker.created
Webhook event data.object has the following structure:

{
	"workerId": "workerId",
	"externalWorkerId": "externalWorkerId"
}

Worker Profile Updated

This event is sent when a worker's profile has been updated.

This is a "catch-all" event that's sent when any change is made to a worker's profile. When receiving this event, clients can retrieve the complete worker profile to re-sync their local copies of that profile data by calling the Retrieve a worker endpoint.

Actions that trigger this event include:

• Updating a data field on a worker's profile, such as an email address, default position and pay rate, approval group, and so on
• Marking a worker's profile as "Separated"

Webhook event type: worker.profile-updated
Webhook event data.object has the following structure:

{
	"workerId": "workerId",
	"externalWorkerId": "externalWorkerId"
}

Worker Profile Deleted

This event is sent when a worker's profile has been deleted.

A worker's profile can only be deleted if no payments have ever been approved and transacted to their bank account, card, or other deposit destination. Once a payment has been transacted, the profile can no longer be deleted, and must be marked as "Separated" instead (see the Worker Terminated event).

Webhook event type: worker.deleted
Webhook event data.object has the following structure:

{
	"workerId": "workerId",
	"externalWorkerId": "externalWorkerId"
}

Worker Terminated

This event is sent when a worker is separated, whether from the Everee app or through the Separate an Employee or Separate a Contractor endpoints.

It's sent once, when the separation is recorded. Changing an existing separation, or cancelling one, doesn't send it again; those changes are sent as worker.profile-updated events.

separationDate is the worker's last day, which can be in the past or the future.

Webhook event type: worker.terminated
Webhook event data.object has the following structure:

{
	"workerId": "workerId",
	"externalWorkerId": "externalWorkerId",
	"separationDate": "2025-08-15"
}

TIN Verification Status Changed

This event is sent when a worker's Taxpayer Identifier Number (an SSN or EIN, depending on the worker's profile configuration) has either been successfully verified against the individual or business name on their Everee profile, or has failed to be verified due to a mismatch.

When a failure happens, it means that either the TIN or the individual or business name on the worker's profile needs to be changed to match the records on file with the IRS or the Social Security Administration. Workers whose profiles have failed TIN verification cannot have W-2 or 1099 forms filed accurately, and their information must be updated in order for Everee to file those forms accurately.

When a worker's TIN or name (individual or business) is updated on their profile, their TIN information is automatically scheduled for re-verification. It may succeed or fail that subsequent event, so it's possible to receive this event multiple times for the same worker.

The tinVerificationStatus field will contain one of the following values:

Webhook event type: worker.tin-verification-status-changed
Webhook event data.object has the following structure:

{
	"workerId": "workerId",
	"externalWorkerId": "externalWorkerId",
	"tinVerificationStatus": "VERIFICATION_FAILED"
}

Report Completed or Errored

Everee sends these events when a report you requested through the Reports API finishes. After report.completed, retrieve the report run to get the download link. errorMessage is only present on report.errored.

Webhook event type: report.completed
Webhook event data.object has the following structure:

{
	"reportId": "8841",
	"reportType": "PAYMENTS_BY_PAY_PERIOD",
	"status": "COMPLETED"
}

If the report couldn't be generated, you receive a report.errored event instead, with the reason in errorMessage.

Webhook event type: report.errored
Webhook event data.object has the following structure:

{
	"reportId": "8842",
	"reportType": "FUNDING",
	"status": "ERRORED",
	"errorMessage": "No funding transactions found."
}