Guides

Webhook Events Overview

The Everee platform sends notifications when certain events occur. These notifications are webhook events published to an endpoint listening for these events in your platform.

During account configuration, you can provide a Target URL—an HTTPS URL that will receive webhook event payloads—to enable webhook delivery from Everee to your platform. Talk to your Partner Success manager about enabling webhook events.

When a webhook event is sent to your target URL, the payload has the following structure:

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

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
}

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: payment.updated-payment-method
Webhook event data.object has this structure:

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

Payment Paid

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

This event is not available by default, and requires Everee review before enabling for a customer account.

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

{
	"workerId": "workerId",
	"externalWorkerId": "externalWorkerId",
	"paymentId": "98765432",
	"grossAmount": { "amount": "500.00", "currency": "USD" },
	"netAmount": { "amount": "441.21", "currency": "USD" },
}

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.

Webhook event type: payment.deposit-returned
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"

This event is not available by default, and requires Everee review before enabling for a customer account.

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 Profile Updated" event).

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

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

Worker Onboarding Locked

This event is sent when a worker's onboarding workflow has been locked.

When an onboarding is locked, a worker cannot retry or continue onboarding until their onboarding is unlocked. This can happen when a worker enters a duplicate or invalid taxpayer identifier number (such as an SSN or ITIN) multiple times.

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

{
	"workerId": "workerId",
	"externalWorkerId": "externalWorkerId",
	"onboardingLockedAt": "1682736572", // Epoch seconds
	"onboardingLocked": true
}

TIN Verification Failed

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

When this 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.

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

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

Updated 8 days ago