Payroll Run Events

Audience: company. These events follow a company's payroll: its payroll runs, their funding, the net payouts to workers, and the requirements that must be fixed before payroll can process. They're sent to the company's webhook endpoints, in the company envelope, with the same signature and retries as every other company event. Verify each event as described in Authenticating events.

Each event's data.object is the same object the API returns for that resource, so you don't need to fetch it. Fields with no value are sent as null.

Events are notifications. They can arrive more than once, and a payroll run can change status several times within seconds, so make your handler idempotent and compare status rather than counting events.

🚧

net-payout.paid must be turned on

Every event on this page is sent to every webhook endpoint, except net-payout.paid. Everee sends net-payout.paid only to endpoints it has been turned on for. Contact Everee Customer Success to turn it on.

Payroll Run Created

Sent when a payroll run is created: a regular run when the company's payroll calendar creates a pay period, with status UNOPENED, or an off-cycle run when you create one, with status OPEN.

Webhook event type: payroll-run.created

{
  "id": "4821",
  "type": "REGULAR",
  "periodStart": "2026-11-02",
  "periodEnd": "2026-11-15",
  "targetPayDate": null,
  "status": "UNOPENED",
  "approvalDeadline": null,
  "reopenDeadline": null,
  "processingBlockedDeadline": null,
  "itemCount": 0,
  "paymentCount": 0,
  "totalNetPay": { "amount": "0.00", "currency": "USD" }
}

Payroll Run Status Changed

Sent every time a payroll run's status changes, whatever changed it: your request, a calculation finishing, money moving, or a deadline passing. Each change is sent, even when a run passes through several statuses within seconds. See Payroll run statuses.

Webhook event type: payroll-run.status-changed

{
  "id": "4821",
  "type": "REGULAR",
  "periodStart": "2026-11-02",
  "periodEnd": "2026-11-15",
  "targetPayDate": "2026-11-20",
  "status": "READY",
  "approvalDeadline": "2026-11-18T17:30:00Z",
  "reopenDeadline": null,
  "processingBlockedDeadline": null,
  "itemCount": 1240,
  "paymentCount": 212,
  "totalNetPay": { "amount": "248310.55", "currency": "USD" },
  "previousStatus": "CALCULATING"
}

Payroll Run Funded and Funding Failed

Sent when a payroll run's funding is collected from the company's funding account (payroll-run.funded), or when it fails or is returned (payroll-run.funding-failed). See Funding and When a funding debit is returned.

Webhook event type: payroll-run.funded or payroll-run.funding-failed

{
  "id": "30118",
  "payrollRunId": "4821",
  "status": "FUNDED",
  "amount": { "amount": "48210.55", "currency": "USD" },
  "transferType": "ACH",
  "fundingDate": "2026-11-18",
  "resolutionDisposition": null,
  "resolutionInstructions": null,
  "previousFundingId": null
}

The event's resource is the payroll run, so the envelope's resource ID is the run's id, and payrollRunId in the object is the same.

Net Payout Events

Sent for each payout to a worker:

• net-payout.paid when the payout is paid: a direct deposit when it's submitted to the bank, other types once they're delivered. The object's status is PAID.
• net-payout.returned when the payout comes back, for example because the bank account was closed. The object's status is RETURNED.
• net-payout.retried when a returned payout is retried. The object is the returned payout, now SUPERSEDED, and supersededByIds names the retry. When the retry is paid, net-payout.paid is sent for it.

A payment split across accounts has a payout for each, and each gets its own events. These events are also sent for payouts on payments outside a payroll run, with payrollRunId null.

Webhook event type: net-payout.paid, net-payout.returned or net-payout.retried

{
  "id": "77310",
  "paymentId": "190554",
  "payrollRunId": "4821",
  "workerId": "6f1c2a9e-4b7d-4a51-9a40-2f6c8d1e7b33",
  "externalWorkerId": "emp-1042",
  "type": "DIRECT_DEPOSIT",
  "directDepositInfo": {
    "nickname": "Checking",
    "routingNumber": "121140399",
    "accountLast4": "4431"
  },
  "payCardInfo": null,
  "netAmount": { "amount": "1612.40", "currency": "USD" },
  "status": "PAID",
  "previousNetPayoutId": null,
  "supersededByIds": []
}

The object includes the bank's routing number and the account's last four digits for a direct deposit, or the card's last four digits for a pay card. Handle it as you would other payment details. See Net Payouts API for the types and statuses.

Requirement Events

Sent when a requirement opens (requirement.created) and when it's resolved (requirement.resolved). Use them to prompt the right person to fix a requirement before payroll day. See Requirement types.

Webhook event type: requirement.created or requirement.resolved

{
  "id": "5530",
  "subjectType": "WORKER",
  "subjectId": "emp-1042",
  "workerId": "6f1c2a9e-4b7d-4a51-9a40-2f6c8d1e7b33",
  "externalWorkerId": "emp-1042",
  "sourceDomain": "WORKER_PROFILE",
  "type": "INVALID_BANK_ACCOUNT",
  "status": "OPEN",
  "resolutionInstructions": "Update the worker's direct deposit bank account with a valid routing and account number.",
  "resolvedAt": null,
  "earliestRecheckAt": null
}

For a worker without an externalWorkerId, subjectId is their workerId, and externalWorkerId is null. For a company requirement, subjectType is COMPANY, subjectId is the company's ID, and the worker fields are null.